@ekodb/ekodb-client 0.15.2 → 0.17.0

package/dist/client.d.ts

@@ -4,7 +4,7 @@
 import { QueryBuilder } from "./query-builder";
 import { SearchQuery, SearchResponse } from "./search";
 import { Schema, SchemaBuilder, CollectionMetadata } from "./schema";
-import { Script, FunctionResult } from "./functions";
+import { UserFunction, FunctionResult } from "./functions";
 export interface Record {
     [key: string]: any;
 }
@@ -156,6 +156,7 @@ export interface CreateChatSessionRequest {
     llm_provider: string;
     llm_model?: string;
     system_prompt?: string;
+    agent_id?: string;
     bypass_ripple?: boolean;
     parent_id?: string;
     branch_point_idx?: number;
@@ -171,6 +172,9 @@ export interface ChatMessageRequest {
     max_iterations?: number;
     tool_config?: ToolConfig;
     llm_model?: string;
+    client_tools?: ClientToolDefinition[];
+    confirm_tools?: string[];
+    exclude_tools?: string[];
 }
 export interface TokenUsage {
     prompt_tokens: number;
@@ -193,6 +197,7 @@ export interface ChatSession {
     llm_model: string;
     collections: CollectionConfig[];
     system_prompt?: string;
+    agent_id?: string;
     title?: string;
     message_count: number;
 }
@@ -285,23 +290,6 @@ export interface RawCompletionRequest {
 export interface RawCompletionResponse {
     content: string;
 }
-/**
- * User function definition - reusable sequence of Functions that can be called by Scripts
- */
-export interface UserFunction {
-    label: string;
-    name: string;
-    description?: string;
-    version?: string;
-    parameters: {
-        [key: string]: ParameterDefinition;
-    };
-    functions: FunctionStageConfig[];
-    tags?: string[];
-    id?: string;
-    created_at?: string;
-    updated_at?: string;
-}
 /**
  * Parameter definition for functions
  */
@@ -821,6 +809,11 @@ export declare class EkoDBClient {
      * Send a message in an existing chat session
      */
     chatMessage(sessionId: string, request: ChatMessageRequest): Promise<ChatResponse>;
+    /**
+     * Submit a client tool result for an in-flight SSE chat stream.
+     * 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 message in an existing chat session via SSE streaming.
      *
@@ -902,29 +895,29 @@ export declare class EkoDBClient {
      */
     getChatMessage(sessionId: string, messageId: string): Promise<Record>;
     /**
-     * Save a new script definition
+     * Save a new function definition
      */
-    saveScript(script: Script): Promise<string>;
+    saveFunction(script: UserFunction): Promise<string>;
     /**
-     * Get a script by ID
+     * Get a function by ID
      */
-    getScript(id: string): Promise<Script>;
+    getFunction(id: string): Promise<UserFunction>;
     /**
-     * List all scripts, optionally filtered by tags
+     * List all functions, optionally filtered by tags
      */
-    listScripts(tags?: string[]): Promise<Script[]>;
+    listFunctions(tags?: string[]): Promise<UserFunction[]>;
     /**
-     * Update an existing script by ID
+     * Update an existing function by ID
      */
-    updateScript(id: string, script: Script): Promise<void>;
+    updateFunction(id: string, script: UserFunction): Promise<void>;
     /**
-     * Delete a script by ID
+     * Delete a function by ID
      */
-    deleteScript(id: string): Promise<void>;
+    deleteFunction(id: string): Promise<void>;
     /**
-     * Call a saved script by ID or label
+     * Call a saved function by ID or label
      */
-    callScript(idOrLabel: string, params?: {
+    callFunction(idOrLabel: string, params?: {
         [key: string]: any;
     }): Promise<FunctionResult>;
     /**
@@ -1058,6 +1051,17 @@ export declare class EkoDBClient {
      * @returns Number of documents in the collection
      */
     countDocuments(collection: string): Promise<number>;
+    /**
+     * Subscribe to collection mutations via SSE (Server-Sent Events).
+     *
+     * Returns an EventStream that emits MutationNotification events.
+     * Use this when WebSocket connections aren't available (e.g. behind
+     * reverse proxies that block WS upgrades).
+     */
+    subscribeSSE(collection: string, options?: {
+        filterField?: string;
+        filterValue?: string;
+    }): EventStream<MutationNotification>;
     /**
      * Create a WebSocket client
      */

package/dist/client.js

@@ -1098,6 +1098,18 @@ class EkoDBClient {
     async chatMessage(sessionId, request) {
         return this.makeRequest("POST", `/api/chat/${sessionId}/messages`, request, 0, true);
     }
+    /**
+     * Submit a client tool result for an in-flight SSE chat stream.
+     * Unblocks ekoDB's tool loop so it can feed the result to the LLM.
+     */
+    async submitChatToolResult(chatId, callId, success, result, error) {
+        await this.makeRequest("POST", `/api/chat/${chatId}/tool-result`, {
+            call_id: callId,
+            success,
+            ...(result !== undefined && { result }),
+            ...(error !== undefined && { error }),
+        }, 0, true);
+    }
     /**
      * Send a message in an existing chat session via SSE streaming.
      *
@@ -1307,41 +1319,41 @@ class EkoDBClient {
     // SCRIPTS API
     // ========================================================================
     /**
-     * Save a new script definition
+     * Save a new function definition
      */
-    async saveScript(script) {
+    async saveFunction(script) {
         const result = await this.makeRequest("POST", "/api/functions", script);
         return result.id;
     }
     /**
-     * Get a script by ID
+     * Get a function by ID
      */
-    async getScript(id) {
+    async getFunction(id) {
         return this.makeRequest("GET", `/api/functions/${id}`);
     }
     /**
-     * List all scripts, optionally filtered by tags
+     * List all functions, optionally filtered by tags
      */
-    async listScripts(tags) {
+    async listFunctions(tags) {
         const params = tags ? `?tags=${tags.join(",")}` : "";
         return this.makeRequest("GET", `/api/functions${params}`);
     }
     /**
-     * Update an existing script by ID
+     * Update an existing function by ID
      */
-    async updateScript(id, script) {
+    async updateFunction(id, script) {
         await this.makeRequest("PUT", `/api/functions/${id}`, script);
     }
     /**
-     * Delete a script by ID
+     * Delete a function by ID
      */
-    async deleteScript(id) {
+    async deleteFunction(id) {
         await this.makeRequest("DELETE", `/api/functions/${id}`);
     }
     /**
-     * Call a saved script by ID or label
+     * Call a saved function by ID or label
      */
-    async callScript(idOrLabel, params) {
+    async callFunction(idOrLabel, params) {
         return this.makeRequest("POST", `/api/functions/${idOrLabel}`, params || {});
     }
     // ========================================================================
@@ -1613,6 +1625,99 @@ class EkoDBClient {
         const records = await this.find(collection, query);
         return records.length;
     }
+    /**
+     * Subscribe to collection mutations via SSE (Server-Sent Events).
+     *
+     * Returns an EventStream that emits MutationNotification events.
+     * Use this when WebSocket connections aren't available (e.g. behind
+     * reverse proxies that block WS upgrades).
+     */
+    subscribeSSE(collection, options) {
+        const stream = new EventStream();
+        (async () => {
+            try {
+                let token = await this.getToken();
+                if (!token) {
+                    await this.refreshToken();
+                    token = await this.getToken();
+                }
+                let url = `${this.baseURL}/api/subscribe/${encodeURIComponent(collection)}`;
+                const params = [];
+                if (options?.filterField)
+                    params.push(`filter_field=${encodeURIComponent(options.filterField)}`);
+                if (options?.filterValue)
+                    params.push(`filter_value=${encodeURIComponent(options.filterValue)}`);
+                if (params.length > 0)
+                    url += `?${params.join("&")}`;
+                const response = await fetch(url, {
+                    method: "GET",
+                    headers: {
+                        Accept: "text/event-stream",
+                        Authorization: `Bearer ${token}`,
+                    },
+                });
+                if (!response.ok) {
+                    const body = await response.text();
+                    stream.emit("error", `SSE subscribe failed (${response.status}): ${body}`);
+                    stream.close();
+                    return;
+                }
+                const reader = response.body?.getReader();
+                if (!reader) {
+                    stream.emit("error", "SSE subscribe failed: streaming not supported");
+                    stream.close();
+                    return;
+                }
+                const decoder = new TextDecoder("utf-8");
+                let buffer = "";
+                let eventType = "";
+                let dataLines = [];
+                while (!stream.closed) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += decoder.decode(value, { stream: true });
+                    const lines = buffer.split("\n");
+                    buffer = lines.pop() ?? "";
+                    for (const line of lines) {
+                        if (line === "") {
+                            // End of event block
+                            if (eventType === "mutation" && dataLines.length > 0) {
+                                try {
+                                    const payload = JSON.parse(dataLines.join("\n"));
+                                    stream.emit("event", {
+                                        collection: payload.collection,
+                                        event: payload.event,
+                                        recordIds: payload.record_ids,
+                                        records: payload.records,
+                                        timestamp: payload.timestamp,
+                                    });
+                                }
+                                catch {
+                                    // skip malformed data
+                                }
+                            }
+                            eventType = "";
+                            dataLines = [];
+                            continue;
+                        }
+                        if (line.startsWith("event: ")) {
+                            eventType = line.slice(7).trim();
+                        }
+                        else if (line.startsWith("data: ")) {
+                            dataLines.push(line.slice(6).trim());
+                        }
+                    }
+                }
+                stream.close();
+            }
+            catch (err) {
+                stream.emit("error", err.message ?? String(err));
+                stream.close();
+            }
+        })();
+        return stream;
+    }
     /**
      * Create a WebSocket client
      */

package/dist/client.test.js

@@ -590,14 +590,14 @@ function mockErrorResponse(status, message) {
             parameters: {},
             functions: [],
         };
-        const result = await client.saveScript(script);
+        const result = await client.saveFunction(script);
         (0, vitest_1.expect)(result).toBeDefined();
     });
     (0, vitest_1.it)("gets script by ID", async () => {
         const client = createTestClient();
         mockTokenResponse();
         mockJsonResponse({ id: "func_123", label: "my_function" });
-        const result = await client.getScript("func_123");
+        const result = await client.getFunction("func_123");
         (0, vitest_1.expect)(result).toBeDefined();
     });
     (0, vitest_1.it)("updates script", async () => {
@@ -610,7 +610,7 @@ function mockErrorResponse(status, message) {
             parameters: {},
             functions: [],
         };
-        await (0, vitest_1.expect)(client.updateScript("func_123", script)).resolves.not.toThrow();
+        await (0, vitest_1.expect)(client.updateFunction("func_123", script)).resolves.not.toThrow();
     });
 });
 (0, vitest_1.describe)("EkoDBClient chat advanced", () => {
@@ -2023,3 +2023,204 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(mockFetch).toHaveBeenCalledTimes(2);
     });
 });
+// ============================================================================
+// agent_id Tests
+// ============================================================================
+(0, vitest_1.describe)("agent_id on chat types", () => {
+    (0, vitest_1.it)("CreateChatSessionRequest includes agent_id", () => {
+        const req = {
+            collections: [{ collection_name: "docs" }],
+            llm_provider: "openai",
+            agent_id: "my-agent",
+        };
+        (0, vitest_1.expect)(req.agent_id).toBe("my-agent");
+    });
+    (0, vitest_1.it)("CreateChatSessionRequest omits agent_id when undefined", () => {
+        const req = {
+            collections: [],
+            llm_provider: "openai",
+        };
+        (0, vitest_1.expect)(req.agent_id).toBeUndefined();
+    });
+    (0, vitest_1.it)("ChatSession includes agent_id", () => {
+        const session = {
+            chat_id: "c1",
+            created_at: "2026-01-01",
+            updated_at: "2026-01-01",
+            llm_provider: "openai",
+            llm_model: "gpt-4",
+            collections: [],
+            agent_id: "bot-1",
+            message_count: 0,
+        };
+        (0, vitest_1.expect)(session.agent_id).toBe("bot-1");
+    });
+    (0, vitest_1.it)("ChatSession allows missing agent_id", () => {
+        const session = {
+            chat_id: "c1",
+            created_at: "2026-01-01",
+            updated_at: "2026-01-01",
+            llm_provider: "openai",
+            llm_model: "gpt-4",
+            collections: [],
+            message_count: 0,
+        };
+        (0, vitest_1.expect)(session.agent_id).toBeUndefined();
+    });
+});
+// ============================================================================
+// client_tools / confirm_tools / exclude_tools Tests
+// ============================================================================
+(0, vitest_1.describe)("ChatMessageRequest tool fields", () => {
+    (0, vitest_1.it)("includes client_tools, confirm_tools, exclude_tools", () => {
+        const req = {
+            message: "hello",
+            client_tools: [
+                {
+                    name: "weather",
+                    description: "Get weather",
+                    parameters: { type: "object" },
+                },
+            ],
+            confirm_tools: ["shell_exec"],
+            exclude_tools: ["file_delete"],
+        };
+        (0, vitest_1.expect)(req.client_tools).toHaveLength(1);
+        (0, vitest_1.expect)(req.client_tools[0].name).toBe("weather");
+        (0, vitest_1.expect)(req.confirm_tools).toEqual(["shell_exec"]);
+        (0, vitest_1.expect)(req.exclude_tools).toEqual(["file_delete"]);
+    });
+    (0, vitest_1.it)("tool fields are optional", () => {
+        const req = { message: "hi" };
+        (0, vitest_1.expect)(req.client_tools).toBeUndefined();
+        (0, vitest_1.expect)(req.confirm_tools).toBeUndefined();
+        (0, vitest_1.expect)(req.exclude_tools).toBeUndefined();
+    });
+    (0, vitest_1.it)("ClientToolDefinition has correct shape", () => {
+        const tool = {
+            name: "calc",
+            description: "Calculator",
+            parameters: { type: "object", properties: {} },
+        };
+        (0, vitest_1.expect)(tool.name).toBe("calc");
+        (0, vitest_1.expect)(tool.description).toBe("Calculator");
+        (0, vitest_1.expect)(tool.parameters.type).toBe("object");
+    });
+});
+// ============================================================================
+// submitChatToolResult Tests
+// ============================================================================
+(0, vitest_1.describe)("submitChatToolResult", () => {
+    (0, vitest_1.it)("sends tool result to correct endpoint", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({});
+        await client.submitChatToolResult("chat-123", "call-456", true, {
+            temp: "72F",
+        });
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledTimes(2);
+        const call = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(call[0]).toContain("/api/chat/chat-123/tool-result");
+        const body = JSON.parse(call[1].body);
+        (0, vitest_1.expect)(body.call_id).toBe("call-456");
+        (0, vitest_1.expect)(body.success).toBe(true);
+        (0, vitest_1.expect)(body.result.temp).toBe("72F");
+    });
+    (0, vitest_1.it)("sends error result", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({});
+        await client.submitChatToolResult("chat-123", "call-456", false, undefined, "tool crashed");
+        const call = mockFetch.mock.calls[1];
+        const body = JSON.parse(call[1].body);
+        (0, vitest_1.expect)(body.success).toBe(false);
+        (0, vitest_1.expect)(body.error).toBe("tool crashed");
+        (0, vitest_1.expect)(body.result).toBeUndefined();
+    });
+});
+// ============================================================================
+// subscribeSSE Tests
+// ============================================================================
+(0, vitest_1.describe)("subscribeSSE", () => {
+    /** Create a mock ReadableStream from a string */
+    function mockReadableStream(data) {
+        const encoder = new TextEncoder();
+        const bytes = encoder.encode(data);
+        let sent = false;
+        return {
+            getReader: () => ({
+                read: async () => {
+                    if (!sent) {
+                        sent = true;
+                        return { value: bytes, done: false };
+                    }
+                    return { value: undefined, done: true };
+                },
+            }),
+        };
+    }
+    (0, vitest_1.it)("parses mutation events from SSE stream", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        const sseBody = "event: subscribed\ndata: {}\n\n" +
+            'event: mutation\ndata: {"collection":"orders","event":"insert","record_ids":["r1"],"timestamp":"t1"}\n\n' +
+            'event: mutation\ndata: {"collection":"orders","event":"update","record_ids":["r2"],"timestamp":"t2"}\n\n';
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            body: mockReadableStream(sseBody),
+            headers: new Headers({ "content-type": "text/event-stream" }),
+        });
+        const stream = client.subscribeSSE("orders");
+        const events = [];
+        await new Promise((resolve) => {
+            stream.on("event", (e) => events.push(e));
+            stream.on("close", resolve);
+            setTimeout(resolve, 100);
+        });
+        (0, vitest_1.expect)(events).toHaveLength(2);
+        (0, vitest_1.expect)(events[0].event).toBe("insert");
+        (0, vitest_1.expect)(events[0].recordIds).toEqual(["r1"]);
+        (0, vitest_1.expect)(events[1].event).toBe("update");
+        (0, vitest_1.expect)(events[1].recordIds).toEqual(["r2"]);
+    });
+    (0, vitest_1.it)("passes filter params in URL", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            body: mockReadableStream(""),
+            headers: new Headers({ "content-type": "text/event-stream" }),
+        });
+        client.subscribeSSE("orders", {
+            filterField: "status",
+            filterValue: "active",
+        });
+        // Wait for async fetch
+        await new Promise((r) => setTimeout(r, 50));
+        const call = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(call[0]).toContain("/api/subscribe/orders");
+        (0, vitest_1.expect)(call[0]).toContain("filter_field=status");
+        (0, vitest_1.expect)(call[0]).toContain("filter_value=active");
+    });
+    (0, vitest_1.it)("emits error on HTTP failure", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockFetch.mockResolvedValueOnce({
+            ok: false,
+            status: 401,
+            text: async () => "Unauthorized",
+            headers: new Headers(),
+        });
+        const stream = client.subscribeSSE("orders");
+        const errors = [];
+        await new Promise((resolve) => {
+            stream.on("error", (e) => errors.push(e));
+            stream.on("close", resolve);
+            setTimeout(resolve, 100);
+        });
+        (0, vitest_1.expect)(errors).toHaveLength(1);
+        (0, vitest_1.expect)(errors[0]).toContain("401");
+    });
+});