@ekodb/ekodb-client 0.13.0 → 0.15.0

package/README.md

@@ -348,6 +348,76 @@ for complete working examples:
 - `client_user_functions.ts` - User functions API
 - And more...
 
+### Goals, Tasks, and Agents
+
+```typescript
+import { EkoDBClient } from "@ekodb/ekodb-client";
+
+const client = new EkoDBClient("http://localhost:8080", "your-api-key");
+await client.init();
+
+// Goals
+const goal = await client.goalCreate({
+  title: "Migrate data",
+  status: "active",
+});
+const goals = await client.goalList();
+await client.goalComplete("goal-id", { summary: "Done" });
+await client.goalApprove("goal-id");
+
+// Tasks
+const task = await client.taskCreate({
+  title: "Backup",
+  schedule: "0 0 * * *",
+});
+await client.taskStart("task-id");
+await client.taskSucceed("task-id", { records: 1500 });
+
+// Agents
+const agent = await client.agentCreate({
+  name: "processor",
+  model: "gpt-4.1",
+});
+const agents = await client.agentList();
+```
+
+### Schedules
+
+```typescript
+// Create a schedule
+const sched = await client.createSchedule({
+  name: "nightly",
+  cron: "0 2 * * *",
+});
+
+// Pause a schedule
+await client.pauseSchedule("sched-id");
+```
+
+### WebSocket Chat Streaming
+
+```typescript
+const ws = client.websocket("ws://localhost:8080");
+
+const stream = await ws.chatSend(chatId, "What is the capital of France?");
+stream.on("event", (event) => {
+  switch (event.type) {
+    case "chunk":
+      process.stdout.write(event.content);
+      break;
+    case "end":
+      console.log(`\nDone (context: ${event.contextWindow} tokens)`);
+      break;
+    case "toolCall":
+      ws.sendToolResult(chatId, event.callId, true, result);
+      break;
+    case "error":
+      console.error(event.error);
+      break;
+  }
+});
+```
+
 ## License
 
 MIT

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;
@@ -320,6 +321,7 @@ export declare class EkoDBClient {
     private baseURL;
     private apiKey;
     private token;
+    private tokenExpiry;
     private shouldRetry;
     private maxRetries;
     private format;
@@ -342,15 +344,24 @@ export declare class EkoDBClient {
      */
     refreshToken(): Promise<void>;
     /**
-     * Get the current authentication token.
-     * Returns null if not yet authenticated. Call refreshToken() first.
+     * Get a valid authentication token.
+     *
+     * Returns a cached token if it has more than 60s of validity remaining.
+     * Otherwise fetches a new one via refreshToken(). This means callers
+     * never need to handle token refresh themselves — every getToken() call
+     * returns a token that's valid for at least 60 more seconds.
      */
-    getToken(): string | null;
+    getToken(): Promise<string | null>;
     /**
-     * Clear the cached authentication token.
+     * Clear the cached authentication token and expiry.
      * The next request will trigger a fresh token exchange.
      */
     clearTokenCache(): void;
+    /**
+     * Extract the `exp` claim from a JWT without verifying the signature.
+     * Returns the Unix timestamp (seconds) of expiry, or null if parsing fails.
+     */
+    private extractJWTExpiry;
     /**
      * Extract rate limit information from response headers
      */
@@ -756,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
      */
@@ -777,10 +802,37 @@ export declare class EkoDBClient {
      * console.log(resp.content);
      */
     rawCompletion(request: RawCompletionRequest): Promise<RawCompletionResponse>;
+    /**
+     * Stateless raw LLM completion via SSE streaming.
+     *
+     * Same as rawCompletion() but uses Server-Sent Events to keep the
+     * connection alive. Preferred for deployed instances where reverse proxies
+     * may kill idle HTTP connections before the LLM responds.
+     */
+    rawCompletionStream(request: RawCompletionRequest): Promise<RawCompletionResponse>;
+    /**
+     * Stateless raw LLM completion via SSE streaming with token-level progress.
+     *
+     * Same as rawCompletionStream() but invokes `onToken` with each token as it
+     * arrives, allowing callers to show real-time progress.
+     */
+    rawCompletionStreamWithProgress(request: RawCompletionRequest, onToken: (token: string) => void): Promise<RawCompletionResponse>;
     /**
      * Send a message in an existing chat session
      */
     chatMessage(sessionId: string, request: ChatMessageRequest): Promise<ChatResponse>;
+    /**
+     * Send a message in an existing chat session via SSE streaming.
+     *
+     * Returns an EventStream that emits ChatStreamEvent objects as they arrive:
+     * - `{ type: "chunk", content: "..." }` for each token
+     * - `{ type: "end", messageId, executionTimeMs, tokenUsage?, contextWindow? }` when complete
+     * - `{ type: "error", error: "..." }` on failure
+     *
+     * Preferred over chatMessage() for long-running responses where reverse
+     * proxies may kill idle HTTP connections before the LLM responds.
+     */
+    chatMessageStream(chatId: string, request: ChatMessageRequest): EventStream<ChatStreamEvent>;
     /**
      * Get a chat session by ID
      */
@@ -904,6 +956,96 @@ export declare class EkoDBClient {
      * @param label - The user function label
      */
     deleteUserFunction(label: string): Promise<void>;
+    /** Create a new goal */
+    goalCreate(data: Record): Promise<Record>;
+    /** List all goals */
+    goalList(): Promise<Record>;
+    /** Get a goal by ID */
+    goalGet(id: string): Promise<Record>;
+    /** Update a goal by ID */
+    goalUpdate(id: string, data: Record): Promise<Record>;
+    /** Delete a goal by ID */
+    goalDelete(id: string): Promise<void>;
+    /** Create a new goal template */
+    goalTemplateCreate(data: Record): Promise<Record>;
+    /** List all goal templates */
+    goalTemplateList(): Promise<Record>;
+    /** Get a goal template by ID */
+    goalTemplateGet(id: string): Promise<Record>;
+    /** Update a goal template by ID */
+    goalTemplateUpdate(id: string, data: Record): Promise<Record>;
+    /** Delete a goal template by ID */
+    goalTemplateDelete(id: string): Promise<void>;
+    /** Search goals */
+    goalSearch(query: string): Promise<Record>;
+    /** Mark a goal as complete (status -> pending_review) */
+    goalComplete(id: string, data: Record): Promise<Record>;
+    /** Approve a goal (status -> in_progress) */
+    goalApprove(id: string): Promise<Record>;
+    /** Reject a goal (status -> failed) */
+    goalReject(id: string, data: Record): Promise<Record>;
+    /** Start a goal step (status -> in_progress) */
+    goalStepStart(id: string, stepIndex: number): Promise<Record>;
+    /** Complete a goal step with result */
+    goalStepComplete(id: string, stepIndex: number, data: Record): Promise<Record>;
+    /** Fail a goal step with error */
+    goalStepFail(id: string, stepIndex: number, data: Record): Promise<Record>;
+    /** Create a new scheduled task */
+    taskCreate(data: Record): Promise<Record>;
+    /** List all scheduled tasks */
+    taskList(): Promise<Record>;
+    /** Get a task by ID */
+    taskGet(id: string): Promise<Record>;
+    /** Update a task by ID */
+    taskUpdate(id: string, data: Record): Promise<Record>;
+    /** Delete a task by ID */
+    taskDelete(id: string): Promise<void>;
+    /** Get tasks that are due at the given time */
+    taskDue(now: string): Promise<Record>;
+    /** Start a task (status -> running) */
+    taskStart(id: string): Promise<Record>;
+    /** Mark a task as succeeded */
+    taskSucceed(id: string, data: Record): Promise<Record>;
+    /** Mark a task as failed */
+    taskFail(id: string, data: Record): Promise<Record>;
+    /** Pause a task */
+    taskPause(id: string): Promise<Record>;
+    /** Resume a paused task */
+    taskResume(id: string, data: Record): Promise<Record>;
+    /** Create a new agent */
+    agentCreate(data: Record): Promise<Record>;
+    /** List all agents */
+    agentList(): Promise<Record>;
+    /** Get an agent by ID */
+    agentGet(id: string): Promise<Record>;
+    /** Get an agent by name */
+    agentGetByName(name: string): Promise<Record>;
+    /** Update an agent by ID */
+    agentUpdate(id: string, data: Record): Promise<Record>;
+    /** Delete an agent by ID */
+    agentDelete(id: string): Promise<void>;
+    /** Get agents by deployment ID */
+    agentsByDeployment(deploymentId: string): Promise<Record>;
+    /** Get documents linked to a KV key */
+    kvGetLinks(key: string): Promise<Record>;
+    /** Link a document to a KV key */
+    kvLink(key: string, collection: string, documentId: string): Promise<Record>;
+    /** Unlink a document from a KV key */
+    kvUnlink(key: string, collection: string, documentId: string): Promise<Record>;
+    /** Create a new schedule */
+    createSchedule(data: Record): Promise<Record>;
+    /** List all schedules */
+    listSchedules(): Promise<Record>;
+    /** Get a schedule by ID */
+    getSchedule(id: string): Promise<Record>;
+    /** Update a schedule */
+    updateSchedule(id: string, data: Record): Promise<Record>;
+    /** Delete a schedule */
+    deleteSchedule(id: string): Promise<void>;
+    /** Pause a schedule */
+    pauseSchedule(id: string): Promise<Record>;
+    /** Resume a schedule */
+    resumeSchedule(id: string): Promise<Record>;
     /**
      * Check if a collection exists
      * @param collection - Collection name to check
@@ -1032,6 +1174,8 @@ export type ChatStreamEvent = {
     tokenUsage?: any;
     toolCallHistory?: any;
     executionTimeMs: number;
+    /** Model's context window size in tokens. */
+    contextWindow?: number;
 } | {
     type: "toolCall";
     chatId: string;
@@ -1116,6 +1260,15 @@ 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>;
+    /**
+     * Stateless raw LLM completion via WebSocket.
+     *
+     * Sends a RawComplete message and waits for the Success response.
+     * Preferred over HTTP for deployed instances: the persistent WSS
+     * connection is already authenticated and won't be killed by reverse
+     * proxy timeouts.
+     */
+    rawCompletion(request: RawCompletionRequest): Promise<RawCompletionResponse>;
     /**
      * Close the WebSocket connection.
      */