@ekodb/ekodb-client 0.12.0 → 0.14.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

@@ -40,8 +40,6 @@ export interface ClientConfig {
     shouldRetry?: boolean;
     /** Maximum number of retry attempts (default: 3) */
     maxRetries?: number;
-    /** Request timeout in milliseconds (default: 30000) */
-    timeout?: number;
     /** Serialization format (default: MessagePack for best performance, use Json for debugging) */
     format?: SerializationFormat;
 }
@@ -110,6 +108,24 @@ export interface BatchDeleteOptions {
     bypassRipple?: boolean;
     transactionId?: string;
 }
+export interface DistinctValuesOptions {
+    /** Optional filter expression (same format as find() filter). */
+    filter?: any;
+    /** Bypass ripple propagation for this query. */
+    bypassRipple?: boolean;
+    /** Bypass cache for this query. */
+    bypassCache?: boolean;
+}
+export interface DistinctValuesResponse {
+    /** Collection that was queried. */
+    collection: string;
+    /** Field whose distinct values were returned. */
+    field: string;
+    /** Unique values, sorted alphabetically. */
+    values: any[];
+    /** Number of distinct values. */
+    count: number;
+}
 export interface CollectionConfig {
     collection_name: string;
     fields?: string[];
@@ -252,6 +268,22 @@ export interface EmbedResponse {
     model: string;
     dimensions: number;
 }
+/**
+ * Request for stateless raw LLM completion — no session, no history, no RAG.
+ */
+export interface RawCompletionRequest {
+    system_prompt: string;
+    message: string;
+    provider?: string;
+    model?: string;
+    max_tokens?: number;
+}
+/**
+ * Response from a raw LLM completion request.
+ */
+export interface RawCompletionResponse {
+    content: string;
+}
 /**
  * User function definition - reusable sequence of Functions that can be called by Scripts
  */
@@ -288,9 +320,9 @@ export declare class EkoDBClient {
     private baseURL;
     private apiKey;
     private token;
+    private tokenExpiry;
     private shouldRetry;
     private maxRetries;
-    private timeout;
     private format;
     private rateLimitInfo;
     constructor(config: string | ClientConfig, apiKey?: string);
@@ -309,7 +341,26 @@ export declare class EkoDBClient {
     /**
      * Refresh the authentication token
      */
-    private refreshToken;
+    refreshToken(): Promise<void>;
+    /**
+     * 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(): Promise<string | null>;
+    /**
+     * 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
      */
@@ -362,6 +413,14 @@ export declare class EkoDBClient {
      * Find a document by ID
      */
     findById(collection: string, id: string): 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
+     */
+    findByIdWithProjection(collection: string, id: string, selectFields?: string[], excludeFields?: string[]): Promise<Record>;
     /**
      * Update a document
      * @param collection - Collection name
@@ -370,6 +429,31 @@ export declare class EkoDBClient {
      * @param options - Optional parameters (bypassRipple, transactionId, bypassCache, selectFields, excludeFields)
      */
     update(collection: string, id: string, record: Record, options?: UpdateOptions): Promise<Record>;
+    /**
+     * Apply an atomic field action to a single field of a record.
+     *
+     * Use this instead of `update()` for safe concurrent modifications like
+     * incrementing counters, pushing to arrays, or arithmetic operations.
+     *
+     * @param collection - Collection name
+     * @param id - Record ID
+     * @param action - The atomic action: increment, decrement, multiply, divide, modulo,
+     *                 push, pop, shift, unshift, remove, append, clear
+     * @param field - The field name to apply the action to
+     * @param value - The value for the action (omit for pop/shift/clear)
+     */
+    updateWithAction(collection: string, id: string, action: string, field: string, value?: any): Promise<Record>;
+    /**
+     * Apply a sequence of atomic field actions to a record in a single request.
+     *
+     * All actions are applied atomically — the record is fetched once, all actions
+     * run in order, and the result is persisted in a single update.
+     *
+     * @param collection - Collection name
+     * @param id - Record ID
+     * @param actions - Array of [action, field, value] tuples
+     */
+    updateWithActionSequence(collection: string, id: string, actions: [string, string, any][]): Promise<Record>;
     /**
      * Delete a document
      * @param collection - Collection name
@@ -657,6 +741,27 @@ export declare class EkoDBClient {
      * ```
      */
     search(collection: string, query: SearchQuery): Promise<SearchResponse>;
+    /**
+     * Get distinct (unique) values for a field across all records in a collection.
+     *
+     * Results are deduplicated and sorted alphabetically. Supports an optional filter
+     * to restrict which records are examined.
+     *
+     * @param collection - Collection name
+     * @param field - Field to get distinct values for
+     * @param options - Optional filter and bypass flags
+     *
+     * @example
+     * // All distinct statuses
+     * const resp = await client.distinctValues("orders", "status");
+     * console.log(resp.values); // ["active", "cancelled", "shipped"]
+     *
+     * // Only statuses for US orders
+     * const resp = await client.distinctValues("orders", "status", {
+     *   filter: { type: "Condition", content: { field: "region", operator: "Eq", value: "us" } }
+     * });
+     */
+    distinctValues(collection: string, field: string, options?: DistinctValuesOptions): Promise<DistinctValuesResponse>;
     /**
      * Health check - verify the ekoDB server is responding
      */
@@ -665,10 +770,54 @@ export declare class EkoDBClient {
      * Create a new chat session
      */
     createChatSession(request: CreateChatSessionRequest): Promise<ChatResponse>;
+    /**
+     * Stateless raw LLM completion — no session, no history, no RAG.
+     *
+     * Sends a system prompt and user message directly to the LLM via ekoDB
+     * and returns the raw text response without any context injection or
+     * conversation management. Use this for structured-output tasks such as
+     * planning where the response must be parsed programmatically.
+     *
+     * @example
+     * const resp = await client.rawCompletion({
+     *   system_prompt: "You are a helpful assistant.",
+     *   message: "Summarize this in JSON.",
+     *   max_tokens: 2048,
+     * });
+     * 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
      */
@@ -718,6 +867,12 @@ export declare class EkoDBClient {
      * @returns ChatModels object with models organized by provider
      */
     getChatModels(): Promise<ChatModels>;
+    /**
+     * Get all built-in server-side chat tool definitions.
+     * Returns a list of tool objects with name, description, and parameters fields.
+     * Used by planning agents to discover available tools dynamically.
+     */
+    getChatTools(): Promise<object[]>;
     /**
      * Get available models for a specific provider
      * @param provider - Provider name (e.g., "openai", "anthropic", "perplexity")
@@ -786,6 +941,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
@@ -896,24 +1141,121 @@ export declare class EkoDBClient {
      */
     findAllWithLimit(collection: string, limit: number): Promise<Record[]>;
 }
+/** Mutation notification from a subscription. */
+export interface MutationNotification {
+    collection: string;
+    event: string;
+    recordIds: string[];
+    records?: any;
+    timestamp: string;
+}
+/** A chunk/event from a streaming chat response. */
+export type ChatStreamEvent = {
+    type: "chunk";
+    content: string;
+} | {
+    type: "end";
+    messageId: string;
+    tokenUsage?: any;
+    toolCallHistory?: any;
+    executionTimeMs: number;
+    /** Model's context window size in tokens. */
+    contextWindow?: number;
+} | {
+    type: "toolCall";
+    chatId: string;
+    callId: string;
+    toolName: string;
+    arguments: any;
+} | {
+    type: "error";
+    error: string;
+};
+/** Definition for a client-side tool the LLM can call. */
+export interface ClientToolDefinition {
+    name: string;
+    description: string;
+    parameters: any;
+}
+/** Options for chatSend. */
+export interface ChatSendOptions {
+    bypassRipple?: boolean;
+    clientTools?: ClientToolDefinition[];
+    maxIterations?: number;
+    confirmTools?: string[];
+    excludeTools?: string[];
+}
+/** Options for subscribe. */
+export interface SubscribeOptions {
+    filterField?: string;
+    filterValue?: string;
+}
+/** EventEmitter-like interface for subscriptions and chat streams. */
+export declare class EventStream<_T = unknown> {
+    private listeners;
+    private _closed;
+    on(event: string, listener: (data: any) => void): this;
+    /** @internal */
+    emit(event: string, data?: any): void;
+    get closed(): boolean;
+    /** @internal */
+    close(): void;
+}
 /**
- * WebSocket client for real-time queries
+ * WebSocket client for real-time queries, subscriptions, and chat streaming.
  */
 export declare class WebSocketClient {
     private wsURL;
     private token;
     private ws;
+    private dispatcherRunning;
+    private pendingRequests;
+    private subscriptions;
+    private chatStreams;
+    private registerToolsAck;
     constructor(wsURL: string, token: string);
+    private messageCounter;
+    private genMessageId;
     /**
-     * Connect to WebSocket
+     * Connect and start the dispatcher.
      */
-    private connect;
+    private ensureConnected;
+    private spawnDispatcher;
+    private routeMessage;
+    private sendRequest;
     /**
-     * Find all records in a collection via WebSocket
+     * Find all records in a collection via WebSocket.
      */
     findAll(collection: string): Promise<Record[]>;
     /**
-     * Close the WebSocket connection
+     * Subscribe to mutation notifications on a collection.
+     * Returns an EventStream that emits "mutation" events.
+     */
+    subscribe(collection: string, options?: SubscribeOptions): Promise<EventStream<MutationNotification>>;
+    /**
+     * Send a chat message and receive a streaming response.
+     * Returns an EventStream that emits "event" with ChatStreamEvent objects.
+     */
+    chatSend(chatId: string, message: string, options?: ChatSendOptions): Promise<EventStream<ChatStreamEvent>>;
+    /**
+     * Register client-side tools for a chat session.
+     */
+    registerClientTools(chatId: string, tools: ClientToolDefinition[]): Promise<void>;
+    /**
+     * 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.
      */
     close(): void;
 }