@ekodb/ekodb-client 0.2.1 → 0.4.0

package/dist/client.d.ts

@@ -4,9 +4,19 @@
 import { QueryBuilder } from "./query-builder";
 import { SearchQuery, SearchQueryBuilder, SearchResponse } from "./search";
 import { Schema, SchemaBuilder, CollectionMetadata } from "./schema";
+import { Script, FunctionResult } from "./functions";
 export interface Record {
     [key: string]: any;
 }
+/**
+ * Serialization format for client-server communication
+ */
+export declare enum SerializationFormat {
+    /** JSON format (default, human-readable) */
+    Json = "Json",
+    /** MessagePack format (binary, 2-3x faster) */
+    MessagePack = "MessagePack"
+}
 /**
  * Rate limit information from the server
  */
@@ -32,6 +42,8 @@ export interface ClientConfig {
     maxRetries?: number;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /** Serialization format (default: MessagePack for best performance, use Json for debugging) */
+    format?: SerializationFormat;
 }
 /**
  * Rate limit error
@@ -155,6 +167,7 @@ export declare class EkoDBClient {
     private shouldRetry;
     private maxRetries;
     private timeout;
+    private format;
     private rateLimitInfo;
     constructor(config: string | ClientConfig, apiKey?: string);
     /**
@@ -181,6 +194,12 @@ export declare class EkoDBClient {
      * Sleep for a specified number of seconds
      */
     private sleep;
+    /**
+     * Helper to determine if a path should use JSON
+     * Only CRUD operations (insert/update/delete/batch) use MessagePack
+     * Everything else uses JSON for compatibility
+     */
+    private shouldUseJSON;
     /**
      * Make an HTTP request to the ekoDB API with retry logic
      */
@@ -227,18 +246,19 @@ export declare class EkoDBClient {
     /**
      * Batch insert multiple documents
      */
-    batchInsert(collection: string, records: Record[]): Promise<Record[]>;
+    batchInsert(collection: string, records: Record[], bypassRipple?: boolean): Promise<BatchOperationResult>;
     /**
      * Batch update multiple documents
      */
     batchUpdate(collection: string, updates: Array<{
         id: string;
         data: Record;
-    }>): Promise<Record[]>;
+        bypassRipple?: boolean;
+    }>): Promise<BatchOperationResult>;
     /**
      * Batch delete multiple documents
      */
-    batchDelete(collection: string, ids: string[]): Promise<number>;
+    batchDelete(collection: string, ids: string[], bypassRipple?: boolean): Promise<BatchOperationResult>;
     /**
      * Set a key-value pair
      */
@@ -376,6 +396,32 @@ export declare class EkoDBClient {
      * Merge multiple chat sessions into one
      */
     mergeChatSessions(request: MergeSessionsRequest): Promise<ChatSessionResponse>;
+    /**
+     * Save a new script definition
+     */
+    saveScript(script: Script): Promise<string>;
+    /**
+     * Get a script by ID
+     */
+    getScript(id: string): Promise<Script>;
+    /**
+     * List all scripts, optionally filtered by tags
+     */
+    listScripts(tags?: string[]): Promise<Script[]>;
+    /**
+     * Update an existing script by ID
+     */
+    updateScript(id: string, script: Script): Promise<void>;
+    /**
+     * Delete a script by ID
+     */
+    deleteScript(id: string): Promise<void>;
+    /**
+     * Call a saved script by ID or label
+     */
+    callScript(idOrLabel: string, params?: {
+        [key: string]: any;
+    }): Promise<FunctionResult>;
     /**
      * Create a WebSocket client
      */

package/dist/client.js

@@ -36,10 +36,21 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebSocketClient = exports.EkoDBClient = exports.MergeStrategy = exports.RateLimitError = void 0;
+exports.WebSocketClient = exports.EkoDBClient = exports.MergeStrategy = exports.RateLimitError = exports.SerializationFormat = void 0;
+const msgpack_1 = require("@msgpack/msgpack");
 const query_builder_1 = require("./query-builder");
 const search_1 = require("./search");
 const schema_1 = require("./schema");
+/**
+ * Serialization format for client-server communication
+ */
+var SerializationFormat;
+(function (SerializationFormat) {
+    /** JSON format (default, human-readable) */
+    SerializationFormat["Json"] = "Json";
+    /** MessagePack format (binary, 2-3x faster) */
+    SerializationFormat["MessagePack"] = "MessagePack";
+})(SerializationFormat || (exports.SerializationFormat = SerializationFormat = {}));
 /**
  * Rate limit error
  */
@@ -68,6 +79,7 @@ class EkoDBClient {
             this.shouldRetry = true;
             this.maxRetries = 3;
             this.timeout = 30000;
+            this.format = SerializationFormat.MessagePack; // Default to MessagePack for 2-3x performance
         }
         else {
             this.baseURL = config.baseURL;
@@ -75,6 +87,7 @@ class EkoDBClient {
             this.shouldRetry = config.shouldRetry ?? true;
             this.maxRetries = config.maxRetries ?? 3;
             this.timeout = config.timeout ?? 30000;
+            this.format = config.format ?? SerializationFormat.MessagePack; // Default to MessagePack for 2-3x performance
         }
     }
     /**
@@ -138,29 +151,72 @@ class EkoDBClient {
     sleep(seconds) {
         return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
     }
+    /**
+     * Helper to determine if a path should use JSON
+     * Only CRUD operations (insert/update/delete/batch) use MessagePack
+     * Everything else uses JSON for compatibility
+     */
+    shouldUseJSON(path) {
+        // ONLY these operations support MessagePack
+        const msgpackPaths = [
+            "/api/insert/",
+            "/api/batch_insert/",
+            "/api/update/",
+            "/api/batch_update/",
+            "/api/delete/",
+            "/api/batch_delete/",
+        ];
+        // Check if path starts with any MessagePack-supported operation
+        for (const prefix of msgpackPaths) {
+            if (path.startsWith(prefix)) {
+                return false; // Use MessagePack
+            }
+        }
+        // Everything else uses JSON
+        return true;
+    }
     /**
      * Make an HTTP request to the ekoDB API with retry logic
      */
-    async makeRequest(method, path, data, attempt = 0) {
+    async makeRequest(method, path, data, attempt = 0, forceJson = false) {
         if (!this.token) {
             await this.refreshToken();
         }
+        // Determine content type and serialization based on path
+        // Only CRUD operations support MessagePack, everything else uses JSON
+        const shouldForceJson = forceJson || this.shouldUseJSON(path);
+        const isMessagePack = !shouldForceJson && this.format === SerializationFormat.MessagePack;
+        const contentType = isMessagePack
+            ? "application/msgpack"
+            : "application/json";
+        // Note: Modern fetch API automatically handles gzip/deflate decompression
+        // when server sends Content-Encoding header. No additional configuration needed.
         const options = {
             method,
             headers: {
                 Authorization: `Bearer ${this.token}`,
-                "Content-Type": "application/json",
+                "Content-Type": contentType,
+                Accept: contentType,
             },
         };
         if (data) {
-            options.body = JSON.stringify(data);
+            options.body = isMessagePack
+                ? (0, msgpack_1.encode)(data)
+                : JSON.stringify(data);
         }
         try {
             const response = await fetch(`${this.baseURL}${path}`, options);
             // Extract rate limit info from successful responses
             if (response.ok) {
                 this.extractRateLimitInfo(response);
-                return response.json();
+                // Deserialize based on format
+                if (isMessagePack) {
+                    const buffer = await response.arrayBuffer();
+                    return (0, msgpack_1.decode)(new Uint8Array(buffer));
+                }
+                else {
+                    return response.json();
+                }
             }
             // Handle rate limiting (429)
             if (response.status === 429) {
@@ -168,7 +224,7 @@ class EkoDBClient {
                 if (this.shouldRetry && attempt < this.maxRetries) {
                     console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
                     await this.sleep(retryAfter);
-                    return this.makeRequest(method, path, data, attempt + 1);
+                    return this.makeRequest(method, path, data, attempt + 1, forceJson);
                 }
                 throw new RateLimitError(retryAfter);
             }
@@ -179,7 +235,7 @@ class EkoDBClient {
                 const retryDelay = 10;
                 console.log(`Service unavailable. Retrying after ${retryDelay} seconds...`);
                 await this.sleep(retryDelay);
-                return this.makeRequest(method, path, data, attempt + 1);
+                return this.makeRequest(method, path, data, attempt + 1, forceJson);
             }
             // Handle other errors
             const text = await response.text();
@@ -193,7 +249,7 @@ class EkoDBClient {
                 const retryDelay = 3;
                 console.log(`Network error. Retrying after ${retryDelay} seconds...`);
                 await this.sleep(retryDelay);
-                return this.makeRequest(method, path, data, attempt + 1);
+                return this.makeRequest(method, path, data, attempt + 1, forceJson);
             }
             throw error;
         }
@@ -255,57 +311,65 @@ class EkoDBClient {
     /**
      * Batch insert multiple documents
      */
-    async batchInsert(collection, records) {
-        const inserts = records.map((data) => ({ data }));
-        const result = await this.makeRequest("POST", `/api/batch/insert/${collection}`, { inserts });
-        return result.successful.map((id) => ({ id }));
+    async batchInsert(collection, records, bypassRipple) {
+        const inserts = records.map((data) => ({
+            data,
+            bypass_ripple: bypassRipple,
+        }));
+        return this.makeRequest("POST", `/api/batch/insert/${collection}`, { inserts });
     }
     /**
      * Batch update multiple documents
      */
     async batchUpdate(collection, updates) {
-        const result = await this.makeRequest("PUT", `/api/batch/update/${collection}`, { updates });
-        return result.successful.map((id) => ({ id }));
+        const formattedUpdates = updates.map((u) => ({
+            id: u.id,
+            data: u.data,
+            bypass_ripple: u.bypassRipple,
+        }));
+        return this.makeRequest("PUT", `/api/batch/update/${collection}`, { updates: formattedUpdates });
     }
     /**
      * Batch delete multiple documents
      */
-    async batchDelete(collection, ids) {
-        const deletes = ids.map((id) => ({ id }));
-        const result = await this.makeRequest("DELETE", `/api/batch/delete/${collection}`, { deletes });
-        return result.successful.length;
+    async batchDelete(collection, ids, bypassRipple) {
+        const deletes = ids.map((id) => ({
+            id: id,
+            bypass_ripple: bypassRipple,
+        }));
+        return this.makeRequest("DELETE", `/api/batch/delete/${collection}`, { deletes });
     }
     /**
      * Set a key-value pair
      */
     async kvSet(key, value) {
-        await this.makeRequest("POST", `/api/kv/set/${encodeURIComponent(key)}`, { value });
+        await this.makeRequest("POST", `/api/kv/set/${encodeURIComponent(key)}`, { value }, 0, true);
     }
     /**
      * Get a value by key
      */
     async kvGet(key) {
-        const result = await this.makeRequest("GET", `/api/kv/get/${encodeURIComponent(key)}`);
+        const result = await this.makeRequest("GET", `/api/kv/get/${encodeURIComponent(key)}`, undefined, 0, true);
         return result.value;
     }
     /**
      * Delete a key
      */
     async kvDelete(key) {
-        await this.makeRequest("DELETE", `/api/kv/delete/${encodeURIComponent(key)}`);
+        await this.makeRequest("DELETE", `/api/kv/delete/${encodeURIComponent(key)}`, undefined, 0, true);
     }
     /**
      * List all collections
      */
     async listCollections() {
-        const result = await this.makeRequest("GET", "/api/collections");
+        const result = await this.makeRequest("GET", "/api/collections", undefined, 0, true);
         return result.collections;
     }
     /**
      * Delete a collection
      */
     async deleteCollection(collection) {
-        await this.makeRequest("DELETE", `/api/collections/${collection}`);
+        await this.makeRequest("DELETE", `/api/collections/${collection}`, undefined, 0, true);
     }
     /**
      * Create a collection with schema
@@ -325,7 +389,7 @@ class EkoDBClient {
      */
     async createCollection(collection, schema) {
         const schemaObj = schema instanceof schema_1.SchemaBuilder ? schema.build() : schema;
-        await this.makeRequest("POST", `/api/collections/${collection}`, schemaObj);
+        await this.makeRequest("POST", `/api/collections/${collection}`, schemaObj, 0, true);
     }
     /**
      * Get collection metadata and schema
@@ -334,7 +398,7 @@ class EkoDBClient {
      * @returns Collection metadata including schema and analytics
      */
     async getCollection(collection) {
-        return this.makeRequest("GET", `/api/collections/${collection}`);
+        return this.makeRequest("GET", `/api/collections/${collection}`, undefined, 0, true);
     }
     /**
      * Get collection schema
@@ -383,26 +447,26 @@ class EkoDBClient {
         const queryObj = searchQuery instanceof search_1.SearchQueryBuilder
             ? searchQuery.build()
             : searchQuery;
-        return this.makeRequest("POST", `/api/search/${collection}`, queryObj);
+        return this.makeRequest("POST", `/api/search/${collection}`, queryObj, 0, true);
     }
     // ========== Chat Methods ==========
     /**
      * Create a new chat session
      */
     async createChatSession(request) {
-        return this.makeRequest("POST", "/api/chat", request);
+        return this.makeRequest("POST", "/api/chat", request, 0, true);
     }
     /**
      * Send a message in an existing chat session
      */
     async chatMessage(sessionId, request) {
-        return this.makeRequest("POST", `/api/chat/${sessionId}/messages`, request);
+        return this.makeRequest("POST", `/api/chat/${sessionId}/messages`, request, 0, true);
     }
     /**
      * Get a chat session by ID
      */
     async getChatSession(sessionId) {
-        return this.makeRequest("GET", `/api/chat/${sessionId}`);
+        return this.makeRequest("GET", `/api/chat/${sessionId}`, undefined, 0, true);
     }
     /**
      * List all chat sessions
@@ -417,7 +481,7 @@ class EkoDBClient {
             params.append("sort", query.sort);
         const queryString = params.toString();
         const path = queryString ? `/api/chat?${queryString}` : "/api/chat";
-        return this.makeRequest("GET", path);
+        return this.makeRequest("GET", path, undefined, 0, true);
     }
     /**
      * Get messages from a chat session
@@ -434,55 +498,96 @@ class EkoDBClient {
         const path = queryString
             ? `/api/chat/${sessionId}/messages?${queryString}`
             : `/api/chat/${sessionId}/messages`;
-        return this.makeRequest("GET", path);
+        return this.makeRequest("GET", path, undefined, 0, true);
     }
     /**
      * Update a chat session
      */
     async updateChatSession(sessionId, request) {
-        return this.makeRequest("PUT", `/api/chat/${sessionId}`, request);
+        return this.makeRequest("PUT", `/api/chat/${sessionId}`, request, 0, true);
     }
     /**
      * Branch a chat session
      */
     async branchChatSession(request) {
-        return this.makeRequest("POST", "/api/chat/branch", request);
+        return this.makeRequest("POST", "/api/chat/branch", request, 0, true);
     }
     /**
      * Delete a chat session
      */
     async deleteChatSession(sessionId) {
-        await this.makeRequest("DELETE", `/api/chat/${sessionId}`);
+        await this.makeRequest("DELETE", `/api/chat/${sessionId}`, undefined, 0, true);
     }
     /**
      * Regenerate an AI response message
      */
     async regenerateMessage(sessionId, messageId) {
-        return this.makeRequest("POST", `/api/chat/${sessionId}/messages/${messageId}/regenerate`);
+        return this.makeRequest("POST", `/api/chat/${sessionId}/messages/${messageId}/regenerate`, undefined, 0, true);
     }
     /**
      * Update a specific message
      */
     async updateChatMessage(sessionId, messageId, content) {
-        await this.makeRequest("PUT", `/api/chat/${sessionId}/messages/${messageId}`, { content });
+        await this.makeRequest("PUT", `/api/chat/${sessionId}/messages/${messageId}`, { content }, 0, true);
     }
     /**
      * Delete a specific message
      */
     async deleteChatMessage(sessionId, messageId) {
-        await this.makeRequest("DELETE", `/api/chat/${sessionId}/messages/${messageId}`);
+        await this.makeRequest("DELETE", `/api/chat/${sessionId}/messages/${messageId}`, undefined, 0, true);
     }
     /**
      * Toggle the "forgotten" status of a message
      */
     async toggleForgottenMessage(sessionId, messageId, forgotten) {
-        await this.makeRequest("PATCH", `/api/chat/${sessionId}/messages/${messageId}/forgotten`, { forgotten });
+        await this.makeRequest("PATCH", `/api/chat/${sessionId}/messages/${messageId}/forgotten`, { forgotten }, 0, true);
     }
     /**
      * Merge multiple chat sessions into one
      */
     async mergeChatSessions(request) {
-        return this.makeRequest("POST", "/api/chat/merge", request);
+        return this.makeRequest("POST", "/api/chat/merge", request, 0, true);
+    }
+    // ========================================================================
+    // SCRIPTS API
+    // ========================================================================
+    /**
+     * Save a new script definition
+     */
+    async saveScript(script) {
+        const result = await this.makeRequest("POST", "/api/functions", script);
+        return result.id;
+    }
+    /**
+     * Get a script by ID
+     */
+    async getScript(id) {
+        return this.makeRequest("GET", `/api/functions/${id}`);
+    }
+    /**
+     * List all scripts, optionally filtered by tags
+     */
+    async listScripts(tags) {
+        const params = tags ? `?tags=${tags.join(",")}` : "";
+        return this.makeRequest("GET", `/api/functions${params}`);
+    }
+    /**
+     * Update an existing script by ID
+     */
+    async updateScript(id, script) {
+        await this.makeRequest("PUT", `/api/functions/${id}`, script);
+    }
+    /**
+     * Delete a script by ID
+     */
+    async deleteScript(id) {
+        await this.makeRequest("DELETE", `/api/functions/${id}`);
+    }
+    /**
+     * Call a saved script by ID or label
+     */
+    async callScript(idOrLabel, params) {
+        return this.makeRequest("POST", `/api/functions/${idOrLabel}`, params || {});
     }
     /**
      * Create a WebSocket client

package/dist/functions.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Scripts API for ekoDB TypeScript client
+ */
+export interface Script {
+    label: string;
+    name: string;
+    description?: string;
+    version: string;
+    parameters: {
+        [key: string]: ParameterDefinition;
+    };
+    functions: FunctionStageConfig[];
+    tags: string[];
+    created_at?: string;
+    updated_at?: string;
+}
+export interface ParameterDefinition {
+    required: boolean;
+    default?: any;
+    description?: string;
+    param_type?: string;
+}
+export type FunctionStageConfig = {
+    type: "FindAll";
+    collection: string;
+} | {
+    type: "Query";
+    collection: string;
+    filter?: Record<string, any>;
+    sort?: SortFieldConfig[];
+    limit?: number;
+    skip?: number;
+} | {
+    type: "Project";
+    fields: string[];
+    exclude: boolean;
+} | {
+    type: "Group";
+    by_fields: string[];
+    functions: GroupFunctionConfig[];
+} | {
+    type: "Count";
+    output_field: string;
+} | {
+    type: "Filter";
+    filter: Record<string, any>;
+} | {
+    type: "Sort";
+    sort: SortFieldConfig[];
+} | {
+    type: "Limit";
+    limit: number;
+} | {
+    type: "Skip";
+    skip: number;
+} | {
+    type: "Insert";
+    collection: string;
+    record: Record<string, any>;
+    bypass_ripple?: boolean;
+    ttl?: number;
+} | {
+    type: "Update";
+    collection: string;
+    filter: Record<string, any>;
+    updates: Record<string, any>;
+    bypass_ripple?: boolean;
+    ttl?: number;
+} | {
+    type: "UpdateById";
+    collection: string;
+    record_id: string;
+    updates: Record<string, any>;
+    bypass_ripple?: boolean;
+    ttl?: number;
+} | {
+    type: "Delete";
+    collection: string;
+    filter: Record<string, any>;
+    bypass_ripple?: boolean;
+} | {
+    type: "DeleteById";
+    collection: string;
+    record_id: string;
+    bypass_ripple?: boolean;
+} | {
+    type: "BatchInsert";
+    collection: string;
+    records: Record<string, any>[];
+    bypass_ripple?: boolean;
+} | {
+    type: "BatchDelete";
+    collection: string;
+    record_ids: string[];
+    bypass_ripple?: boolean;
+} | {
+    type: "HttpRequest";
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: any;
+} | {
+    type: "VectorSearch";
+    collection: string;
+    query_vector: number[];
+    limit?: number;
+    threshold?: number;
+} | {
+    type: "TextSearch";
+    collection: string;
+    query_text: string;
+    fields?: string[];
+    limit?: number;
+    fuzzy?: boolean;
+} | {
+    type: "HybridSearch";
+    collection: string;
+    query_text: string;
+    query_vector?: number[];
+    limit?: number;
+} | {
+    type: "Chat";
+    messages: ChatMessage[];
+    model?: string;
+    temperature?: number;
+    max_tokens?: number;
+} | {
+    type: "Embed";
+    input_field: string;
+    output_field: string;
+    model?: string;
+};
+export interface ChatMessage {
+    role: string;
+    content: string;
+}
+export declare const ChatMessage: {
+    system: (content: string) => ChatMessage;
+    user: (content: string) => ChatMessage;
+    assistant: (content: string) => ChatMessage;
+};
+export interface GroupFunctionConfig {
+    output_field: string;
+    operation: "Sum" | "Average" | "Count" | "Min" | "Max" | "First" | "Last" | "Push";
+    input_field?: string;
+}
+export interface SortFieldConfig {
+    field: string;
+    ascending: boolean;
+}
+export interface FunctionResult {
+    records: Record<string, any>[];
+    stats: FunctionStats;
+}
+export interface FunctionStats {
+    input_count: number;
+    output_count: number;
+    execution_time_ms: number;
+    stages_executed: number;
+    stage_stats: StageStats[];
+}
+export interface StageStats {
+    stage: string;
+    input_count: number;
+    output_count: number;
+    execution_time_ms: number;
+}
+export declare const Stage: {
+    findAll: (collection: string) => FunctionStageConfig;
+    query: (collection: string, filter?: Record<string, any>, sort?: SortFieldConfig[], limit?: number, skip?: number) => FunctionStageConfig;
+    project: (fields: string[], exclude?: boolean) => FunctionStageConfig;
+    group: (by_fields: string[], functions: GroupFunctionConfig[]) => FunctionStageConfig;
+    count: (output_field?: string) => FunctionStageConfig;
+    insert: (collection: string, record: Record<string, any>, bypassRipple?: boolean, ttl?: number) => FunctionStageConfig;
+    update: (collection: string, filter: Record<string, any>, updates: Record<string, any>, bypassRipple?: boolean, ttl?: number) => FunctionStageConfig;
+    updateById: (collection: string, record_id: string, updates: Record<string, any>, bypassRipple?: boolean, ttl?: number) => FunctionStageConfig;
+    delete: (collection: string, filter: Record<string, any>, bypassRipple?: boolean) => FunctionStageConfig;
+    deleteById: (collection: string, record_id: string, bypassRipple?: boolean) => FunctionStageConfig;
+    batchInsert: (collection: string, records: Record<string, any>[], bypassRipple?: boolean) => FunctionStageConfig;
+    batchDelete: (collection: string, record_ids: string[], bypassRipple?: boolean) => FunctionStageConfig;
+    filter: (filter: Record<string, any>) => FunctionStageConfig;
+    sort: (sort: SortFieldConfig[]) => FunctionStageConfig;
+    limit: (limit: number) => FunctionStageConfig;
+    skip: (skip: number) => FunctionStageConfig;
+    httpRequest: (url: string, method?: string, headers?: Record<string, string>, body?: any) => FunctionStageConfig;
+    vectorSearch: (collection: string, query_vector: number[], limit?: number, threshold?: number) => FunctionStageConfig;
+    textSearch: (collection: string, query_text: string, options?: {
+        fields?: string[];
+        limit?: number;
+        fuzzy?: boolean;
+    }) => FunctionStageConfig;
+    hybridSearch: (collection: string, query_text: string, query_vector?: number[], limit?: number) => FunctionStageConfig;
+    chat: (messages: ChatMessage[], model?: string, temperature?: number, max_tokens?: number) => FunctionStageConfig;
+    embed: (input_field: string, output_field: string, model?: string) => FunctionStageConfig;
+};