@ekodb/ekodb-client 0.14.0 → 0.15.1

package/README.md

@@ -328,9 +328,38 @@ const joinResults = await client.find("users", multiQuery);
 
 ### WebSocket Methods
 
-- `findAll(collection: string): Promise<Record[]>`
+**Full CRUD (14 methods):**
+
+- `findAll(collection): Promise<Record[]>`
+- `insert(collection, record, bypassRipple?): Promise<any>`
+- `query(collection, options?): Promise<any[]>`
+- `findById(collection, id): Promise<any>`
+- `update(collection, id, record, bypassRipple?): Promise<any>`
+- `delete(collection, id, bypassRipple?): Promise<void>`
+- `batchInsert(collection, records, bypassRipple?): Promise<any>`
+- `batchUpdate(collection, updates, bypassRipple?): Promise<any>`
+- `batchDelete(collection, ids, bypassRipple?): Promise<void>`
+- `textSearch(collection, query, fields?, limit?): Promise<any[]>`
+- `distinctValues(collection, field, filter?): Promise<any>`
+- `updateWithAction(collection, id, action, field, value?): Promise<any>`
+- `createCollection(name, schema?): Promise<void>`
+- `listCollections(): Promise<string[]>`
+- `deleteCollection(name): Promise<void>`
 - `close(): void`
 
+**Schema Cache:**
+
+```typescript
+import { SchemaCache, extractRecordId } from "@ekodb/ekodb-client";
+
+const cache = new SchemaCache({ enabled: true, ttlSeconds: 300 });
+ws.setSchemaCache(cache);
+
+// Extract IDs correctly with custom primary_key_alias
+const id = extractRecordId(record); // tries "id", "_id"
+const id2 = ws.extractId("users", record); // uses cache
+```
+
 ## Examples
 
 See the

package/dist/client.d.ts

@@ -170,6 +170,7 @@ export interface ChatMessageRequest {
     force_summarize?: boolean;
     max_iterations?: number;
     tool_config?: ToolConfig;
+    llm_model?: string;
 }
 export interface TokenUsage {
     prompt_tokens: number;
@@ -766,6 +767,20 @@ export declare class EkoDBClient {
      * Health check - verify the ekoDB server is responding
      */
     health(): Promise<boolean>;
+    /**
+     * Execute a tool via ekoDB's server-side tool pipeline.
+     *
+     * Calls POST /api/chat/tools/execute which goes through the same
+     * execute_tool function as the LLM tool-calling loop — with all
+     * collection filtering, permission enforcement, and internal collection
+     * blocking. No LLM round-trip.
+     *
+     * @returns The tool result if executed, or null if the server doesn't
+     * support the endpoint (older ekoDB versions).
+     */
+    executeTool(toolName: string, params: {
+        [key: string]: any;
+    }, chatId?: string): Promise<any | null>;
     /**
      * Create a new chat session
      */
@@ -1204,11 +1219,40 @@ export declare class EventStream<_T = unknown> {
 /**
  * WebSocket client for real-time queries, subscriptions, and chat streaming.
  */
+/**
+ * In-memory schema cache with TTL for primary_key_alias resolution.
+ */
+export declare class SchemaCache {
+    private entries;
+    private lruOrder;
+    private enabled;
+    private maxEntries;
+    private ttlMs;
+    constructor(options?: {
+        enabled?: boolean;
+        maxEntries?: number;
+        ttlSeconds?: number;
+    });
+    isEnabled(): boolean;
+    setEnabled(enabled: boolean): void;
+    getAlias(collection: string): string | undefined;
+    insert(collection: string, primaryKeyAlias: string, version: number): void;
+    invalidate(collection: string): void;
+    invalidateAll(): void;
+    handleSchemaChanged(collection: string, version: number, primaryKeyAlias: string): void;
+    get size(): number;
+    private touchLRU;
+}
+/**
+ * Extract record ID from a record object, trying custom alias, "id", then "_id".
+ */
+export declare function extractRecordId(record: Record, extraCandidates?: string[]): string | undefined;
 export declare class WebSocketClient {
     private wsURL;
     private token;
     private ws;
     private dispatcherRunning;
+    private schemaCache;
     private pendingRequests;
     private subscriptions;
     private chatStreams;
@@ -1254,6 +1298,44 @@ export declare class WebSocketClient {
      * proxy timeouts.
      */
     rawCompletion(request: RawCompletionRequest): Promise<RawCompletionResponse>;
+    /** Attach a schema cache for automatic invalidation on SchemaChanged events. */
+    setSchemaCache(cache: SchemaCache): void;
+    /** Extract record ID using the schema cache's primary_key_alias. */
+    extractId(collection: string, record: Record): string | undefined;
+    private sendCRUD;
+    /** Insert a single record via WebSocket. */
+    insert(collection: string, record: Record, bypassRipple?: boolean): Promise<any>;
+    /** Query records via WebSocket. */
+    query(collection: string, options?: {
+        filter?: any;
+        sort?: any;
+        limit?: number;
+        skip?: number;
+    }): Promise<any[]>;
+    /** Find a record by ID via WebSocket. */
+    findById(collection: string, id: string): Promise<any>;
+    /** Update a record by ID via WebSocket. */
+    update(collection: string, id: string, record: Record, bypassRipple?: boolean): Promise<any>;
+    /** Delete a record by ID via WebSocket. */
+    delete(collection: string, id: string, bypassRipple?: boolean): Promise<void>;
+    /** Batch insert multiple records via WebSocket. */
+    batchInsert(collection: string, records: Record[], bypassRipple?: boolean): Promise<any>;
+    /** Batch update multiple records via WebSocket. */
+    batchUpdate(collection: string, updates: [string, Record][], bypassRipple?: boolean): Promise<any>;
+    /** Batch delete records by IDs via WebSocket. */
+    batchDelete(collection: string, ids: string[], bypassRipple?: boolean): Promise<void>;
+    /** Full-text search via WebSocket. */
+    textSearch(collection: string, query: string, fields?: string[], limit?: number): Promise<any[]>;
+    /** Get distinct values for a field via WebSocket. */
+    distinctValues(collection: string, field: string, filter?: any): Promise<any>;
+    /** Apply an atomic field action via WebSocket. */
+    updateWithAction(collection: string, id: string, action: string, field: string, value?: any): Promise<any>;
+    /** Create a collection with optional schema via WebSocket. */
+    createCollection(name: string, schema?: any): Promise<void>;
+    /** List all collections via WebSocket. */
+    listCollections(): Promise<string[]>;
+    /** Delete a collection via WebSocket. */
+    deleteCollection(name: string): Promise<void>;
     /**
      * Close the WebSocket connection.
      */

package/dist/client.js

@@ -36,7 +36,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebSocketClient = 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.SerializationFormat = void 0;
+exports.extractRecordId = extractRecordId;
 const msgpack_1 = require("@msgpack/msgpack");
 const query_builder_1 = require("./query-builder");
 const schema_1 = require("./schema");
@@ -930,6 +931,43 @@ class EkoDBClient {
         }
     }
     // ========== Chat Methods ==========
+    /**
+     * Execute a tool via ekoDB's server-side tool pipeline.
+     *
+     * Calls POST /api/chat/tools/execute which goes through the same
+     * execute_tool function as the LLM tool-calling loop — with all
+     * collection filtering, permission enforcement, and internal collection
+     * blocking. No LLM round-trip.
+     *
+     * @returns The tool result if executed, or null if the server doesn't
+     * support the endpoint (older ekoDB versions).
+     */
+    async executeTool(toolName, params, chatId) {
+        const body = { tool: toolName, params };
+        if (chatId) {
+            body.chat_id = chatId;
+        }
+        try {
+            const result = await this.makeRequest("POST", "/api/chat/tools/execute", body, 0, true);
+            if (result.success) {
+                return result.result;
+            }
+            else {
+                throw new Error(result.error || "tool execution failed");
+            }
+        }
+        catch (err) {
+            // Server doesn't have the endpoint (404) or route mismatch (405)
+            // Parse status from makeRequest error format: "Request failed with status NNN: ..."
+            const message = String(err?.message ?? "");
+            const match = message.match(/Request failed with status (\d+):/);
+            const status = match ? parseInt(match[1], 10) : undefined;
+            if (status === 404 || status === 405) {
+                return null;
+            }
+            throw err;
+        }
+    }
     /**
      * Create a new chat session
      */
@@ -1741,10 +1779,107 @@ exports.EventStream = EventStream;
 /**
  * WebSocket client for real-time queries, subscriptions, and chat streaming.
  */
+/**
+ * In-memory schema cache with TTL for primary_key_alias resolution.
+ */
+class SchemaCache {
+    constructor(options = {}) {
+        this.entries = new Map();
+        this.lruOrder = [];
+        this.enabled = options.enabled ?? false;
+        this.maxEntries = options.maxEntries ?? 100;
+        this.ttlMs = (options.ttlSeconds ?? 300) * 1000;
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    getAlias(collection) {
+        if (!this.enabled)
+            return undefined;
+        const entry = this.entries.get(collection);
+        if (!entry)
+            return undefined;
+        if (Date.now() - entry.cachedAt > this.ttlMs) {
+            this.entries.delete(collection);
+            this.lruOrder = this.lruOrder.filter((c) => c !== collection);
+            return undefined;
+        }
+        this.touchLRU(collection);
+        return entry.primaryKeyAlias;
+    }
+    insert(collection, primaryKeyAlias, version) {
+        if (!this.enabled)
+            return;
+        const isNew = !this.entries.has(collection);
+        this.entries.set(collection, {
+            primaryKeyAlias,
+            version,
+            cachedAt: Date.now(),
+        });
+        if (isNew) {
+            this.lruOrder.push(collection);
+            while (this.lruOrder.length > this.maxEntries) {
+                const oldest = this.lruOrder.shift();
+                this.entries.delete(oldest);
+            }
+        }
+        else {
+            this.touchLRU(collection);
+        }
+    }
+    invalidate(collection) {
+        this.entries.delete(collection);
+        this.lruOrder = this.lruOrder.filter((c) => c !== collection);
+    }
+    invalidateAll() {
+        this.entries.clear();
+        this.lruOrder = [];
+    }
+    handleSchemaChanged(collection, version, primaryKeyAlias) {
+        if (!this.enabled)
+            return;
+        const existing = this.entries.get(collection);
+        if (existing && version <= existing.version)
+            return;
+        this.insert(collection, primaryKeyAlias, version);
+    }
+    get size() {
+        return this.entries.size;
+    }
+    touchLRU(collection) {
+        this.lruOrder = this.lruOrder.filter((c) => c !== collection);
+        this.lruOrder.push(collection);
+    }
+}
+exports.SchemaCache = SchemaCache;
+/**
+ * Extract record ID from a record object, trying custom alias, "id", then "_id".
+ */
+function extractRecordId(record, extraCandidates = []) {
+    for (const key of extraCandidates) {
+        const val = record[key];
+        if (typeof val === "string")
+            return val;
+        if (val && typeof val === "object" && "value" in val)
+            return String(val.value);
+    }
+    for (const key of ["id", "_id"]) {
+        const val = record[key];
+        if (typeof val === "string")
+            return val;
+        if (val && typeof val === "object" && "value" in val)
+            return String(val.value);
+    }
+    return undefined;
+}
 class WebSocketClient {
     constructor(wsURL, token) {
         this.ws = null;
         this.dispatcherRunning = false;
+        this.schemaCache = null;
         // Dispatcher state
         this.pendingRequests = new Map();
         this.subscriptions = new Map();
@@ -1919,6 +2054,12 @@ class WebSocketClient {
                 }
                 break;
             }
+            case "SchemaChanged": {
+                if (this.schemaCache && msg.payload) {
+                    this.schemaCache.handleSchemaChanged(msg.payload.collection, msg.payload.version, msg.payload.primary_key_alias);
+                }
+                break;
+            }
             case "ClientToolCall": {
                 const chatId = msg.payload?.chat_id || msg.payload?.chatId;
                 const stream = this.chatStreams.get(chatId);
@@ -2083,6 +2224,136 @@ class WebSocketClient {
         });
         return { content: payload?.data?.content || "" };
     }
+    /** Attach a schema cache for automatic invalidation on SchemaChanged events. */
+    setSchemaCache(cache) {
+        this.schemaCache = cache;
+    }
+    /** Extract record ID using the schema cache's primary_key_alias. */
+    extractId(collection, record) {
+        const alias = this.schemaCache?.getAlias(collection);
+        return extractRecordId(record, alias ? [alias] : []);
+    }
+    // =========================================================================
+    // WS CRUD Methods — Full Parity with Server
+    // =========================================================================
+    async sendCRUD(msgType, payload) {
+        const messageId = this.genMessageId();
+        const response = await this.sendRequest({
+            type: msgType,
+            messageId,
+            payload,
+        });
+        return response?.data ?? response;
+    }
+    /** Insert a single record via WebSocket. */
+    async insert(collection, record, bypassRipple) {
+        return this.sendCRUD("Insert", {
+            collection,
+            record,
+            ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+        });
+    }
+    /** Query records via WebSocket. */
+    async query(collection, options) {
+        const data = await this.sendCRUD("Query", {
+            collection,
+            ...options,
+        });
+        return Array.isArray(data) ? data : [];
+    }
+    /** Find a record by ID via WebSocket. */
+    async findById(collection, id) {
+        return this.sendCRUD("FindById", { collection, id });
+    }
+    /** Update a record by ID via WebSocket. */
+    async update(collection, id, record, bypassRipple) {
+        return this.sendCRUD("Update", {
+            collection,
+            id,
+            record,
+            ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+        });
+    }
+    /** Delete a record by ID via WebSocket. */
+    async delete(collection, id, bypassRipple) {
+        await this.sendCRUD("Delete", {
+            collection,
+            id,
+            ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+        });
+    }
+    /** Batch insert multiple records via WebSocket. */
+    async batchInsert(collection, records, bypassRipple) {
+        return this.sendCRUD("BatchInsert", {
+            collection,
+            records,
+            ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+        });
+    }
+    /** Batch update multiple records via WebSocket. */
+    async batchUpdate(collection, updates, bypassRipple) {
+        return this.sendCRUD("BatchUpdate", {
+            collection,
+            updates,
+            ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+        });
+    }
+    /** Batch delete records by IDs via WebSocket. */
+    async batchDelete(collection, ids, bypassRipple) {
+        await this.sendCRUD("BatchDelete", {
+            collection,
+            ids,
+            ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+        });
+    }
+    /** Full-text search via WebSocket. */
+    async textSearch(collection, query, fields, limit) {
+        const options = {};
+        if (fields)
+            options.fields = fields;
+        if (limit)
+            options.limit = limit;
+        const data = await this.sendCRUD("TextSearch", {
+            collection,
+            query,
+            ...(Object.keys(options).length > 0 && { options }),
+        });
+        return Array.isArray(data) ? data : [];
+    }
+    /** Get distinct values for a field via WebSocket. */
+    async distinctValues(collection, field, filter) {
+        return this.sendCRUD("DistinctValues", {
+            collection,
+            field,
+            ...(filter && { filter }),
+        });
+    }
+    /** Apply an atomic field action via WebSocket. */
+    async updateWithAction(collection, id, action, field, value) {
+        return this.sendCRUD("UpdateWithAction", {
+            collection,
+            id,
+            action,
+            field,
+            ...(value !== undefined && { value }),
+        });
+    }
+    /** Create a collection with optional schema via WebSocket. */
+    async createCollection(name, schema) {
+        await this.sendCRUD("CreateCollection", {
+            name,
+            schema: schema ?? {},
+        });
+    }
+    /** List all collections via WebSocket. */
+    async listCollections() {
+        const data = await this.sendCRUD("GetCollections", {});
+        return Array.isArray(data) ? data : [];
+    }
+    /** Delete a collection via WebSocket. */
+    async deleteCollection(name) {
+        await this.sendCRUD("DeleteCollection", { name });
+    }
     /**
      * Close the WebSocket connection.
      */

package/dist/client.test.js

@@ -805,6 +805,57 @@ function mockErrorResponse(status, message) {
     });
 });
 // ============================================================================
+// executeTool Tests
+// ============================================================================
+(0, vitest_1.describe)("EkoDBClient executeTool", () => {
+    (0, vitest_1.it)("executes tool successfully", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({
+            success: true,
+            result: { count: 42 },
+        });
+        const result = await client.executeTool("count_records", {
+            collection: "users",
+        });
+        (0, vitest_1.expect)(result).toEqual({ count: 42 });
+    });
+    (0, vitest_1.it)("passes chat_id when provided", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({
+            success: true,
+            result: { value: "hello" },
+        });
+        const result = await client.executeTool("kv_get", { key: "greeting" }, "chat_456");
+        (0, vitest_1.expect)(result).toEqual({ value: "hello" });
+        // Verify the request body included chat_id
+        const lastCall = mockFetch.mock.calls[1];
+        const body = JSON.parse(lastCall[1].body);
+        (0, vitest_1.expect)(body.chat_id).toBe("chat_456");
+        (0, vitest_1.expect)(body.tool).toBe("kv_get");
+        (0, vitest_1.expect)(body.params).toEqual({ key: "greeting" });
+    });
+    (0, vitest_1.it)("throws on tool execution failure", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({
+            success: false,
+            error: "permission denied",
+        });
+        await (0, vitest_1.expect)(client.executeTool("delete_collection", { collection: "system" })).rejects.toThrow("permission denied");
+    });
+    (0, vitest_1.it)("returns null when server does not support endpoint", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockErrorResponse(404, "Not Found");
+        const result = await client.executeTool("count_records", {
+            collection: "users",
+        });
+        (0, vitest_1.expect)(result).toBeNull();
+    });
+});
+// ============================================================================
 // Chat Models Tests
 // ============================================================================
 (0, vitest_1.describe)("EkoDBClient chat models", () => {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { EkoDBClient, WebSocketClient, EventStream, SerializationFormat, MergeStrategy, RateLimitError, } from "./client";
+export { EkoDBClient, WebSocketClient, EventStream, SerializationFormat, MergeStrategy, RateLimitError, SchemaCache, extractRecordId, } from "./client";
 export { QueryBuilder, SortOrder } from "./query-builder";
 export { SearchQueryBuilder } from "./search";
 export { SchemaBuilder, FieldTypeSchemaBuilder, VectorIndexAlgorithm, DistanceMetric, } from "./schema";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Field = exports.getObjectValue = exports.getVectorValue = exports.getSetValue = exports.getArrayValue = exports.getBinaryValue = exports.getBytesValue = exports.getDurationValue = exports.getDecimalValue = exports.getUUIDValue = exports.getDateTimeValue = exports.extractRecord = exports.getValues = exports.getValue = exports.ChatMessage = exports.Stage = exports.JoinBuilder = exports.DistanceMetric = exports.VectorIndexAlgorithm = exports.FieldTypeSchemaBuilder = exports.SchemaBuilder = exports.SearchQueryBuilder = exports.SortOrder = exports.QueryBuilder = exports.RateLimitError = exports.MergeStrategy = exports.SerializationFormat = exports.EventStream = exports.WebSocketClient = exports.EkoDBClient = void 0;
+exports.Field = exports.getObjectValue = exports.getVectorValue = exports.getSetValue = exports.getArrayValue = exports.getBinaryValue = exports.getBytesValue = exports.getDurationValue = exports.getDecimalValue = exports.getUUIDValue = exports.getDateTimeValue = exports.extractRecord = exports.getValues = exports.getValue = exports.ChatMessage = exports.Stage = exports.JoinBuilder = exports.DistanceMetric = exports.VectorIndexAlgorithm = exports.FieldTypeSchemaBuilder = exports.SchemaBuilder = exports.SearchQueryBuilder = exports.SortOrder = exports.QueryBuilder = exports.extractRecordId = exports.SchemaCache = exports.RateLimitError = exports.MergeStrategy = exports.SerializationFormat = exports.EventStream = exports.WebSocketClient = exports.EkoDBClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "EkoDBClient", { enumerable: true, get: function () { return client_1.EkoDBClient; } });
 Object.defineProperty(exports, "WebSocketClient", { enumerable: true, get: function () { return client_1.WebSocketClient; } });
@@ -8,6 +8,8 @@ Object.defineProperty(exports, "EventStream", { enumerable: true, get: function
 Object.defineProperty(exports, "SerializationFormat", { enumerable: true, get: function () { return client_1.SerializationFormat; } });
 Object.defineProperty(exports, "MergeStrategy", { enumerable: true, get: function () { return client_1.MergeStrategy; } });
 Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return client_1.RateLimitError; } });
+Object.defineProperty(exports, "SchemaCache", { enumerable: true, get: function () { return client_1.SchemaCache; } });
+Object.defineProperty(exports, "extractRecordId", { enumerable: true, get: function () { return client_1.extractRecordId; } });
 var query_builder_1 = require("./query-builder");
 Object.defineProperty(exports, "QueryBuilder", { enumerable: true, get: function () { return query_builder_1.QueryBuilder; } });
 Object.defineProperty(exports, "SortOrder", { enumerable: true, get: function () { return query_builder_1.SortOrder; } });

package/package.json

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

package/src/client.test.ts

@@ -1105,6 +1105,80 @@ describe("Convenience methods", () => {
   });
 });
 
+// ============================================================================
+// executeTool Tests
+// ============================================================================
+
+describe("EkoDBClient executeTool", () => {
+  it("executes tool successfully", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({
+      success: true,
+      result: { count: 42 },
+    });
+
+    const result = await client.executeTool("count_records", {
+      collection: "users",
+    });
+
+    expect(result).toEqual({ count: 42 });
+  });
+
+  it("passes chat_id when provided", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({
+      success: true,
+      result: { value: "hello" },
+    });
+
+    const result = await client.executeTool(
+      "kv_get",
+      { key: "greeting" },
+      "chat_456",
+    );
+
+    expect(result).toEqual({ value: "hello" });
+
+    // Verify the request body included chat_id
+    const lastCall = mockFetch.mock.calls[1];
+    const body = JSON.parse(lastCall[1].body);
+    expect(body.chat_id).toBe("chat_456");
+    expect(body.tool).toBe("kv_get");
+    expect(body.params).toEqual({ key: "greeting" });
+  });
+
+  it("throws on tool execution failure", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({
+      success: false,
+      error: "permission denied",
+    });
+
+    await expect(
+      client.executeTool("delete_collection", { collection: "system" }),
+    ).rejects.toThrow("permission denied");
+  });
+
+  it("returns null when server does not support endpoint", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockErrorResponse(404, "Not Found");
+
+    const result = await client.executeTool("count_records", {
+      collection: "users",
+    });
+
+    expect(result).toBeNull();
+  });
+});
+
 // ============================================================================
 // Chat Models Tests
 // ============================================================================

package/src/client.ts

@@ -203,6 +203,7 @@ export interface ChatMessageRequest {
   force_summarize?: boolean;
   max_iterations?: number;
   tool_config?: ToolConfig;
+  llm_model?: string;
 }
 
 export interface TokenUsage {
@@ -1552,6 +1553,54 @@ export class EkoDBClient {
 
   // ========== Chat Methods ==========
 
+  /**
+   * Execute a tool via ekoDB's server-side tool pipeline.
+   *
+   * Calls POST /api/chat/tools/execute which goes through the same
+   * execute_tool function as the LLM tool-calling loop — with all
+   * collection filtering, permission enforcement, and internal collection
+   * blocking. No LLM round-trip.
+   *
+   * @returns The tool result if executed, or null if the server doesn't
+   * support the endpoint (older ekoDB versions).
+   */
+  async executeTool(
+    toolName: string,
+    params: { [key: string]: any },
+    chatId?: string,
+  ): Promise<any | null> {
+    const body: { [key: string]: any } = { tool: toolName, params };
+    if (chatId) {
+      body.chat_id = chatId;
+    }
+
+    try {
+      const result = await this.makeRequest<{ [key: string]: any }>(
+        "POST",
+        "/api/chat/tools/execute",
+        body,
+        0,
+        true, // Force JSON for chat operations
+      );
+
+      if (result.success) {
+        return result.result;
+      } else {
+        throw new Error(result.error || "tool execution failed");
+      }
+    } catch (err: any) {
+      // Server doesn't have the endpoint (404) or route mismatch (405)
+      // Parse status from makeRequest error format: "Request failed with status NNN: ..."
+      const message = String(err?.message ?? "");
+      const match = message.match(/Request failed with status (\d+):/);
+      const status = match ? parseInt(match[1], 10) : undefined;
+      if (status === 404 || status === 405) {
+        return null;
+      }
+      throw err;
+    }
+  }
+
   /**
    * Create a new chat session
    */
@@ -2977,11 +3026,128 @@ export class EventStream<_T = unknown> {
 /**
  * WebSocket client for real-time queries, subscriptions, and chat streaming.
  */
+/**
+ * In-memory schema cache with TTL for primary_key_alias resolution.
+ */
+export class SchemaCache {
+  private entries: Map<
+    string,
+    { primaryKeyAlias: string; version: number; cachedAt: number }
+  > = new Map();
+  private lruOrder: string[] = [];
+  private enabled: boolean;
+  private maxEntries: number;
+  private ttlMs: number;
+
+  constructor(
+    options: {
+      enabled?: boolean;
+      maxEntries?: number;
+      ttlSeconds?: number;
+    } = {},
+  ) {
+    this.enabled = options.enabled ?? false;
+    this.maxEntries = options.maxEntries ?? 100;
+    this.ttlMs = (options.ttlSeconds ?? 300) * 1000;
+  }
+
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+  }
+
+  getAlias(collection: string): string | undefined {
+    if (!this.enabled) return undefined;
+    const entry = this.entries.get(collection);
+    if (!entry) return undefined;
+    if (Date.now() - entry.cachedAt > this.ttlMs) {
+      this.entries.delete(collection);
+      this.lruOrder = this.lruOrder.filter((c) => c !== collection);
+      return undefined;
+    }
+    this.touchLRU(collection);
+    return entry.primaryKeyAlias;
+  }
+
+  insert(collection: string, primaryKeyAlias: string, version: number): void {
+    if (!this.enabled) return;
+    const isNew = !this.entries.has(collection);
+    this.entries.set(collection, {
+      primaryKeyAlias,
+      version,
+      cachedAt: Date.now(),
+    });
+    if (isNew) {
+      this.lruOrder.push(collection);
+      while (this.lruOrder.length > this.maxEntries) {
+        const oldest = this.lruOrder.shift()!;
+        this.entries.delete(oldest);
+      }
+    } else {
+      this.touchLRU(collection);
+    }
+  }
+
+  invalidate(collection: string): void {
+    this.entries.delete(collection);
+    this.lruOrder = this.lruOrder.filter((c) => c !== collection);
+  }
+  invalidateAll(): void {
+    this.entries.clear();
+    this.lruOrder = [];
+  }
+
+  handleSchemaChanged(
+    collection: string,
+    version: number,
+    primaryKeyAlias: string,
+  ): void {
+    if (!this.enabled) return;
+    const existing = this.entries.get(collection);
+    if (existing && version <= existing.version) return;
+    this.insert(collection, primaryKeyAlias, version);
+  }
+
+  get size(): number {
+    return this.entries.size;
+  }
+
+  private touchLRU(collection: string): void {
+    this.lruOrder = this.lruOrder.filter((c) => c !== collection);
+    this.lruOrder.push(collection);
+  }
+}
+
+/**
+ * Extract record ID from a record object, trying custom alias, "id", then "_id".
+ */
+export function extractRecordId(
+  record: Record,
+  extraCandidates: string[] = [],
+): string | undefined {
+  for (const key of extraCandidates) {
+    const val = record[key];
+    if (typeof val === "string") return val;
+    if (val && typeof val === "object" && "value" in val)
+      return String(val.value);
+  }
+  for (const key of ["id", "_id"]) {
+    const val = record[key];
+    if (typeof val === "string") return val;
+    if (val && typeof val === "object" && "value" in val)
+      return String(val.value);
+  }
+  return undefined;
+}
+
 export class WebSocketClient {
   private wsURL: string;
   private token: string;
   private ws: any = null;
   private dispatcherRunning = false;
+  private schemaCache: SchemaCache | null = null;
 
   // Dispatcher state
   private pendingRequests: Map<
@@ -3181,6 +3347,17 @@ export class WebSocketClient {
         break;
       }
 
+      case "SchemaChanged": {
+        if (this.schemaCache && msg.payload) {
+          this.schemaCache.handleSchemaChanged(
+            msg.payload.collection,
+            msg.payload.version,
+            msg.payload.primary_key_alias,
+          );
+        }
+        break;
+      }
+
       case "ClientToolCall": {
         const chatId = msg.payload?.chat_id || msg.payload?.chatId;
         const stream = this.chatStreams.get(chatId);
@@ -3382,6 +3559,200 @@ export class WebSocketClient {
     return { content: payload?.data?.content || "" };
   }
 
+  /** Attach a schema cache for automatic invalidation on SchemaChanged events. */
+  setSchemaCache(cache: SchemaCache): void {
+    this.schemaCache = cache;
+  }
+
+  /** Extract record ID using the schema cache's primary_key_alias. */
+  extractId(collection: string, record: Record): string | undefined {
+    const alias = this.schemaCache?.getAlias(collection);
+    return extractRecordId(record, alias ? [alias] : []);
+  }
+
+  // =========================================================================
+  // WS CRUD Methods — Full Parity with Server
+  // =========================================================================
+
+  private async sendCRUD(msgType: string, payload: any): Promise<any> {
+    const messageId = this.genMessageId();
+    const response = await this.sendRequest({
+      type: msgType,
+      messageId,
+      payload,
+    });
+    return response?.data ?? response;
+  }
+
+  /** Insert a single record via WebSocket. */
+  async insert(
+    collection: string,
+    record: Record,
+    bypassRipple?: boolean,
+  ): Promise<any> {
+    return this.sendCRUD("Insert", {
+      collection,
+      record,
+      ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+    });
+  }
+
+  /** Query records via WebSocket. */
+  async query(
+    collection: string,
+    options?: {
+      filter?: any;
+      sort?: any;
+      limit?: number;
+      skip?: number;
+    },
+  ): Promise<any[]> {
+    const data = await this.sendCRUD("Query", {
+      collection,
+      ...options,
+    });
+    return Array.isArray(data) ? data : [];
+  }
+
+  /** Find a record by ID via WebSocket. */
+  async findById(collection: string, id: string): Promise<any> {
+    return this.sendCRUD("FindById", { collection, id });
+  }
+
+  /** Update a record by ID via WebSocket. */
+  async update(
+    collection: string,
+    id: string,
+    record: Record,
+    bypassRipple?: boolean,
+  ): Promise<any> {
+    return this.sendCRUD("Update", {
+      collection,
+      id,
+      record,
+      ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+    });
+  }
+
+  /** Delete a record by ID via WebSocket. */
+  async delete(
+    collection: string,
+    id: string,
+    bypassRipple?: boolean,
+  ): Promise<void> {
+    await this.sendCRUD("Delete", {
+      collection,
+      id,
+      ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+    });
+  }
+
+  /** Batch insert multiple records via WebSocket. */
+  async batchInsert(
+    collection: string,
+    records: Record[],
+    bypassRipple?: boolean,
+  ): Promise<any> {
+    return this.sendCRUD("BatchInsert", {
+      collection,
+      records,
+      ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+    });
+  }
+
+  /** Batch update multiple records via WebSocket. */
+  async batchUpdate(
+    collection: string,
+    updates: [string, Record][],
+    bypassRipple?: boolean,
+  ): Promise<any> {
+    return this.sendCRUD("BatchUpdate", {
+      collection,
+      updates,
+      ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+    });
+  }
+
+  /** Batch delete records by IDs via WebSocket. */
+  async batchDelete(
+    collection: string,
+    ids: string[],
+    bypassRipple?: boolean,
+  ): Promise<void> {
+    await this.sendCRUD("BatchDelete", {
+      collection,
+      ids,
+      ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+    });
+  }
+
+  /** Full-text search via WebSocket. */
+  async textSearch(
+    collection: string,
+    query: string,
+    fields?: string[],
+    limit?: number,
+  ): Promise<any[]> {
+    const options: any = {};
+    if (fields) options.fields = fields;
+    if (limit) options.limit = limit;
+    const data = await this.sendCRUD("TextSearch", {
+      collection,
+      query,
+      ...(Object.keys(options).length > 0 && { options }),
+    });
+    return Array.isArray(data) ? data : [];
+  }
+
+  /** Get distinct values for a field via WebSocket. */
+  async distinctValues(
+    collection: string,
+    field: string,
+    filter?: any,
+  ): Promise<any> {
+    return this.sendCRUD("DistinctValues", {
+      collection,
+      field,
+      ...(filter && { filter }),
+    });
+  }
+
+  /** Apply an atomic field action via WebSocket. */
+  async updateWithAction(
+    collection: string,
+    id: string,
+    action: string,
+    field: string,
+    value?: any,
+  ): Promise<any> {
+    return this.sendCRUD("UpdateWithAction", {
+      collection,
+      id,
+      action,
+      field,
+      ...(value !== undefined && { value }),
+    });
+  }
+
+  /** Create a collection with optional schema via WebSocket. */
+  async createCollection(name: string, schema?: any): Promise<void> {
+    await this.sendCRUD("CreateCollection", {
+      name,
+      schema: schema ?? {},
+    });
+  }
+
+  /** List all collections via WebSocket. */
+  async listCollections(): Promise<string[]> {
+    const data = await this.sendCRUD("GetCollections", {});
+    return Array.isArray(data) ? data : [];
+  }
+
+  /** Delete a collection via WebSocket. */
+  async deleteCollection(name: string): Promise<void> {
+    await this.sendCRUD("DeleteCollection", { name });
+  }
+
   /**
    * Close the WebSocket connection.
    */

package/src/index.ts

@@ -5,6 +5,8 @@ export {
   SerializationFormat,
   MergeStrategy,
   RateLimitError,
+  SchemaCache,
+  extractRecordId,
 } from "./client";
 export { QueryBuilder, SortOrder } from "./query-builder";
 export { SearchQueryBuilder } from "./search";