@ekodb/ekodb-client 0.15.2 → 0.17.0

package/src/client.ts

@@ -6,7 +6,7 @@ import { encode, decode } from "@msgpack/msgpack";
 import { QueryBuilder, Query as QueryBuilderQuery } 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;
@@ -188,6 +188,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;
@@ -204,6 +205,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 {
@@ -229,6 +233,7 @@ export interface ChatSession {
   llm_model: string;
   collections: CollectionConfig[];
   system_prompt?: string;
+  agent_id?: string;
   title?: string;
   message_count: number;
 }
@@ -335,21 +340,7 @@ 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;
-}
+// UserFunction is defined in functions.ts and re-exported from there.
 
 /**
  * Parameter definition for functions
@@ -1769,6 +1760,31 @@ export class EkoDBClient {
     );
   }
 
+  /**
+   * 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: string,
+    callId: string,
+    success: boolean,
+    result?: any,
+    error?: string,
+  ): Promise<void> {
+    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.
    *
@@ -2106,9 +2122,9 @@ export class EkoDBClient {
   // ========================================================================
 
   /**
-   * Save a new script definition
+   * Save a new function definition
    */
-  async saveScript(script: Script): Promise<string> {
+  async saveFunction(script: UserFunction): Promise<string> {
     const result = await this.makeRequest<{ id: string }>(
       "POST",
       "/api/functions",
@@ -2118,38 +2134,38 @@ export class EkoDBClient {
   }
 
   /**
-   * Get a script by ID
+   * Get a function by ID
    */
-  async getScript(id: string): Promise<Script> {
-    return this.makeRequest<Script>("GET", `/api/functions/${id}`);
+  async getFunction(id: string): Promise<UserFunction> {
+    return this.makeRequest<UserFunction>("GET", `/api/functions/${id}`);
   }
 
   /**
-   * List all scripts, optionally filtered by tags
+   * List all functions, optionally filtered by tags
    */
-  async listScripts(tags?: string[]): Promise<Script[]> {
+  async listFunctions(tags?: string[]): Promise<UserFunction[]> {
     const params = tags ? `?tags=${tags.join(",")}` : "";
-    return this.makeRequest<Script[]>("GET", `/api/functions${params}`);
+    return this.makeRequest<UserFunction[]>("GET", `/api/functions${params}`);
   }
 
   /**
-   * Update an existing script by ID
+   * Update an existing function by ID
    */
-  async updateScript(id: string, script: Script): Promise<void> {
+  async updateFunction(id: string, script: UserFunction): Promise<void> {
     await this.makeRequest<void>("PUT", `/api/functions/${id}`, script);
   }
 
   /**
-   * Delete a script by ID
+   * Delete a function by ID
    */
-  async deleteScript(id: string): Promise<void> {
+  async deleteFunction(id: string): Promise<void> {
     await this.makeRequest<void>("DELETE", `/api/functions/${id}`);
   }
 
   /**
-   * Call a saved script by ID or label
+   * Call a saved function by ID or label
    */
-  async callScript(
+  async callFunction(
     idOrLabel: string,
     params?: { [key: string]: any },
   ): Promise<FunctionResult> {
@@ -2783,6 +2799,115 @@ export class EkoDBClient {
     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: string,
+    options?: { filterField?: string; filterValue?: string },
+  ): EventStream<MutationNotification> {
+    const stream = new EventStream<MutationNotification>();
+
+    (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: string[] = [];
+        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: string[] = [];
+
+        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,
+                  } as MutationNotification);
+                } 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: any) {
+        stream.emit("error", err.message ?? String(err));
+        stream.close();
+      }
+    })();
+
+    return stream;
+  }
+
   /**
    * Create a WebSocket client
    */