@ekodb/ekodb-client 0.11.0 → 0.13.0

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[];
@@ -123,6 +139,18 @@ export interface ChatRequest {
     system_prompt?: string;
     bypass_ripple?: boolean;
 }
+export interface ToolChoice {
+    type: "auto" | "none" | "required" | "tool";
+    name?: string;
+}
+export interface ToolConfig {
+    enabled: boolean;
+    allowed_tools?: string[];
+    allowed_collections?: string[];
+    max_iterations?: number;
+    allow_write_operations?: boolean;
+    tool_choice?: ToolChoice;
+}
 export interface CreateChatSessionRequest {
     collections: CollectionConfig[];
     llm_provider: string;
@@ -132,11 +160,16 @@ export interface CreateChatSessionRequest {
     parent_id?: string;
     branch_point_idx?: number;
     max_context_messages?: number;
+    max_tokens?: number;
+    temperature?: number;
+    tool_config?: ToolConfig;
 }
 export interface ChatMessageRequest {
     message: string;
     bypass_ripple?: boolean;
     force_summarize?: boolean;
+    max_iterations?: number;
+    tool_config?: ToolConfig;
 }
 export interface TokenUsage {
     prompt_tokens: number;
@@ -195,16 +228,21 @@ export interface UpdateSessionRequest {
     llm_model?: string;
     collections?: CollectionConfig[];
     max_context_messages?: number;
+    bypass_ripple?: boolean;
+    title?: string;
+    memory?: any;
 }
 export declare enum MergeStrategy {
     Chronological = "Chronological",
     Summarized = "Summarized",
-    LatestOnly = "LatestOnly"
+    LatestOnly = "LatestOnly",
+    Interleaved = "Interleaved"
 }
 export interface MergeSessionsRequest {
     source_chat_ids: string[];
     target_chat_id: string;
     merge_strategy: MergeStrategy;
+    bypass_ripple?: boolean;
 }
 /**
  * Available chat models by provider
@@ -214,6 +252,38 @@ export interface ChatModels {
     anthropic: string[];
     perplexity: string[];
 }
+/**
+ * Request to generate embeddings
+ */
+export interface EmbedRequest {
+    text?: string;
+    texts?: string[];
+    model?: string;
+}
+/**
+ * Response from embedding generation
+ */
+export interface EmbedResponse {
+    embeddings: number[][];
+    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
  */
@@ -252,7 +322,6 @@ export declare class EkoDBClient {
     private token;
     private shouldRetry;
     private maxRetries;
-    private timeout;
     private format;
     private rateLimitInfo;
     constructor(config: string | ClientConfig, apiKey?: string);
@@ -271,7 +340,17 @@ export declare class EkoDBClient {
     /**
      * Refresh the authentication token
      */
-    private refreshToken;
+    refreshToken(): Promise<void>;
+    /**
+     * Get the current authentication token.
+     * Returns null if not yet authenticated. Call refreshToken() first.
+     */
+    getToken(): string | null;
+    /**
+     * Clear the cached authentication token.
+     * The next request will trigger a fresh token exchange.
+     */
+    clearTokenCache(): void;
     /**
      * Extract rate limit information from response headers
      */
@@ -324,6 +403,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
@@ -332,6 +419,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
@@ -619,6 +731,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
      */
@@ -627,6 +760,23 @@ 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>;
     /**
      * Send a message in an existing chat session
      */
@@ -680,6 +830,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")
@@ -765,13 +921,7 @@ export declare class EkoDBClient {
      */
     websocket(wsURL: string): WebSocketClient;
     /**
-     * Generate embeddings for text using ekoDB's native Functions
-     *
-     * This helper simplifies embedding generation by:
-     * 1. Creating a temporary collection with the text
-     * 2. Running a Script with FindAll + Embed Functions
-     * 3. Extracting and returning the embedding vector
-     * 4. Cleaning up temporary resources
+     * Generate embeddings for a single text
      *
      * @param text - The text to generate embeddings for
      * @param model - The embedding model to use (e.g., "text-embedding-3-small")
@@ -787,6 +937,18 @@ export declare class EkoDBClient {
      * ```
      */
     embed(text: string, model: string): Promise<number[]>;
+    /**
+     * Generate embeddings for multiple texts in a single batch request
+     *
+     * @param texts - Array of texts to generate embeddings for
+     * @param model - The embedding model to use
+     * @returns Array of embedding vectors
+     */
+    embedBatch(texts: string[], model: string): Promise<number[][]>;
+    /**
+     * Internal: make embed API request
+     */
+    private embedRequest;
     /**
      * Perform text search without embeddings
      *
@@ -852,24 +1014,110 @@ 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;
+} | {
+    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>;
+    /**
+     * Close the WebSocket connection.
      */
     close(): void;
 }