@ekodb/ekodb-client 0.3.0 → 0.5.0

package/dist/client.d.ts

@@ -4,6 +4,7 @@
 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;
 }
@@ -395,10 +396,119 @@ 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
      */
     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
+     *
+     * @param text - The text to generate embeddings for
+     * @param model - The embedding model to use (e.g., "text-embedding-3-small")
+     * @returns Array of floats representing the embedding vector
+     *
+     * @example
+     * ```typescript
+     * const embedding = await client.embed(
+     *   "Hello world",
+     *   "text-embedding-3-small"
+     * );
+     * console.log(`Generated ${embedding.length} dimensions`);
+     * ```
+     */
+    embed(text: string, model: string): Promise<number[]>;
+    /**
+     * Perform text search without embeddings
+     *
+     * Simplified text search with full-text matching, fuzzy search, and stemming.
+     *
+     * @param collection - Collection name to search
+     * @param queryText - Search query text
+     * @param limit - Maximum number of results to return
+     * @returns Array of matching records
+     *
+     * @example
+     * ```typescript
+     * const results = await client.textSearch(
+     *   "documents",
+     *   "ownership system",
+     *   10
+     * );
+     * ```
+     */
+    textSearch(collection: string, queryText: string, limit: number): Promise<Record[]>;
+    /**
+     * Perform hybrid search combining text and vector search
+     *
+     * Combines semantic similarity (vector search) with keyword matching (text search)
+     * for more accurate and relevant results.
+     *
+     * @param collection - Collection name to search
+     * @param queryText - Search query text
+     * @param queryVector - Embedding vector for semantic search
+     * @param limit - Maximum number of results to return
+     * @returns Array of matching records
+     *
+     * @example
+     * ```typescript
+     * const embedding = await client.embed(query, "text-embedding-3-small");
+     * const results = await client.hybridSearch(
+     *   "documents",
+     *   query,
+     *   embedding,
+     *   5
+     * );
+     * ```
+     */
+    hybridSearch(collection: string, queryText: string, queryVector: number[], limit: number): Promise<Record[]>;
+    /**
+     * Find all records in a collection with a limit
+     *
+     * Simplified method to query all documents in a collection.
+     *
+     * @param collection - Collection name
+     * @param limit - Maximum number of records to return
+     * @returns Array of records
+     *
+     * @example
+     * ```typescript
+     * const allMessages = await client.findAll("messages", 1000);
+     * console.log(`Found ${allMessages.length} messages`);
+     * ```
+     */
+    findAllWithLimit(collection: string, limit: number): Promise<Record[]>;
 }
 /**
  * WebSocket client for real-time queries

package/dist/client.js

@@ -228,6 +228,13 @@ class EkoDBClient {
                 }
                 throw new RateLimitError(retryAfter);
             }
+            // Handle unauthorized (401) - try refreshing token
+            if (response.status === 401 && attempt === 0) {
+                console.log("Authentication failed, refreshing token...");
+                await this.refreshToken();
+                // Retry with new token
+                return this.makeRequest(method, path, data, attempt + 1, forceJson);
+            }
             // Handle service unavailable (503)
             if (response.status === 503 &&
                 this.shouldRetry &&
@@ -548,12 +555,203 @@ class EkoDBClient {
     async mergeChatSessions(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
      */
     websocket(wsURL) {
         return new WebSocketClient(wsURL, this.token);
     }
+    // ========== RAG Helper Methods ==========
+    /**
+     * 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
+     *
+     * @param text - The text to generate embeddings for
+     * @param model - The embedding model to use (e.g., "text-embedding-3-small")
+     * @returns Array of floats representing the embedding vector
+     *
+     * @example
+     * ```typescript
+     * const embedding = await client.embed(
+     *   "Hello world",
+     *   "text-embedding-3-small"
+     * );
+     * console.log(`Generated ${embedding.length} dimensions`);
+     * ```
+     */
+    async embed(text, model) {
+        const tempCollection = `embed_temp_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        try {
+            // Insert temporary record with the text
+            await this.insert(tempCollection, { text }, undefined);
+            // Create Script with FindAll + Embed Functions
+            const tempLabel = `embed_script_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+            const script = {
+                label: tempLabel,
+                name: "Generate Embedding",
+                description: "Temporary script for embedding generation",
+                version: "1.0",
+                parameters: {},
+                functions: [
+                    {
+                        type: "FindAll",
+                        collection: tempCollection,
+                    },
+                    {
+                        type: "Embed",
+                        input_field: "text",
+                        output_field: "embedding",
+                        model: model,
+                    },
+                ],
+                tags: [],
+            };
+            // Save and execute the script
+            const scriptId = await this.saveScript(script);
+            const result = await this.callScript(scriptId, undefined);
+            // Clean up
+            await this.deleteScript(scriptId).catch(() => { });
+            await this.deleteCollection(tempCollection).catch(() => { });
+            // Extract embedding from result
+            if (result.records && result.records.length > 0) {
+                const record = result.records[0];
+                if (record.embedding && Array.isArray(record.embedding)) {
+                    return record.embedding;
+                }
+            }
+            throw new Error("Failed to extract embedding from result");
+        }
+        catch (error) {
+            // Ensure cleanup even on error
+            await this.deleteCollection(tempCollection).catch(() => { });
+            throw error;
+        }
+    }
+    /**
+     * Perform text search without embeddings
+     *
+     * Simplified text search with full-text matching, fuzzy search, and stemming.
+     *
+     * @param collection - Collection name to search
+     * @param queryText - Search query text
+     * @param limit - Maximum number of results to return
+     * @returns Array of matching records
+     *
+     * @example
+     * ```typescript
+     * const results = await client.textSearch(
+     *   "documents",
+     *   "ownership system",
+     *   10
+     * );
+     * ```
+     */
+    async textSearch(collection, queryText, limit) {
+        const searchQuery = {
+            query: queryText,
+            limit,
+        };
+        const response = await this.search(collection, searchQuery);
+        return response.results.map((r) => r.record);
+    }
+    /**
+     * Perform hybrid search combining text and vector search
+     *
+     * Combines semantic similarity (vector search) with keyword matching (text search)
+     * for more accurate and relevant results.
+     *
+     * @param collection - Collection name to search
+     * @param queryText - Search query text
+     * @param queryVector - Embedding vector for semantic search
+     * @param limit - Maximum number of results to return
+     * @returns Array of matching records
+     *
+     * @example
+     * ```typescript
+     * const embedding = await client.embed(query, "text-embedding-3-small");
+     * const results = await client.hybridSearch(
+     *   "documents",
+     *   query,
+     *   embedding,
+     *   5
+     * );
+     * ```
+     */
+    async hybridSearch(collection, queryText, queryVector, limit) {
+        const searchQuery = {
+            query: queryText,
+            vector: queryVector,
+            limit,
+        };
+        const response = await this.search(collection, searchQuery);
+        return response.results.map((r) => r.record);
+    }
+    /**
+     * Find all records in a collection with a limit
+     *
+     * Simplified method to query all documents in a collection.
+     *
+     * @param collection - Collection name
+     * @param limit - Maximum number of records to return
+     * @returns Array of records
+     *
+     * @example
+     * ```typescript
+     * const allMessages = await client.findAll("messages", 1000);
+     * console.log(`Found ${allMessages.length} messages`);
+     * ```
+     */
+    async findAllWithLimit(collection, limit) {
+        const query = new query_builder_1.QueryBuilder().limit(limit).build();
+        const results = await this.find(collection, query);
+        return results;
+    }
 }
 exports.EkoDBClient = EkoDBClient;
 /**

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;
+};

package/dist/functions.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Scripts API for ekoDB TypeScript client
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Stage = exports.ChatMessage = void 0;
+exports.ChatMessage = {
+    system: (content) => ({
+        role: "system",
+        content: content,
+    }),
+    user: (content) => ({
+        role: "user",
+        content: content,
+    }),
+    assistant: (content) => ({
+        role: "assistant",
+        content: content,
+    }),
+};
+// Stage builder functions
+exports.Stage = {
+    findAll: (collection) => ({
+        type: "FindAll",
+        collection,
+    }),
+    query: (collection, filter, sort, limit, skip) => ({
+        type: "Query",
+        collection,
+        filter,
+        sort,
+        limit,
+        skip,
+    }),
+    project: (fields, exclude = false) => ({
+        type: "Project",
+        fields,
+        exclude,
+    }),
+    group: (by_fields, functions) => ({
+        type: "Group",
+        by_fields,
+        functions,
+    }),
+    count: (output_field = "count") => ({
+        type: "Count",
+        output_field,
+    }),
+    insert: (collection, record, bypassRipple = false, ttl) => ({
+        type: "Insert",
+        collection,
+        record,
+        bypass_ripple: bypassRipple,
+        ttl,
+    }),
+    update: (collection, filter, updates, bypassRipple = false, ttl) => ({
+        type: "Update",
+        collection,
+        filter,
+        updates,
+        bypass_ripple: bypassRipple,
+        ttl,
+    }),
+    updateById: (collection, record_id, updates, bypassRipple = false, ttl) => ({
+        type: "UpdateById",
+        collection,
+        record_id,
+        updates,
+        bypass_ripple: bypassRipple,
+        ttl,
+    }),
+    delete: (collection, filter, bypassRipple = false) => ({
+        type: "Delete",
+        collection,
+        filter,
+        bypass_ripple: bypassRipple,
+    }),
+    deleteById: (collection, record_id, bypassRipple = false) => ({
+        type: "DeleteById",
+        collection,
+        record_id,
+        bypass_ripple: bypassRipple,
+    }),
+    batchInsert: (collection, records, bypassRipple = false) => ({
+        type: "BatchInsert",
+        collection,
+        records,
+        bypass_ripple: bypassRipple,
+    }),
+    batchDelete: (collection, record_ids, bypassRipple = false) => ({
+        type: "BatchDelete",
+        collection,
+        record_ids,
+        bypass_ripple: bypassRipple,
+    }),
+    filter: (filter) => ({
+        type: "Filter",
+        filter,
+    }),
+    sort: (sort) => ({
+        type: "Sort",
+        sort,
+    }),
+    limit: (limit) => ({
+        type: "Limit",
+        limit,
+    }),
+    skip: (skip) => ({
+        type: "Skip",
+        skip,
+    }),
+    httpRequest: (url, method = "GET", headers, body) => ({
+        type: "HttpRequest",
+        url,
+        method,
+        headers,
+        body,
+    }),
+    vectorSearch: (collection, query_vector, limit, threshold) => ({
+        type: "VectorSearch",
+        collection,
+        query_vector,
+        limit,
+        threshold,
+    }),
+    textSearch: (collection, query_text, options) => ({
+        type: "TextSearch",
+        collection,
+        query_text,
+        fields: options?.fields,
+        limit: options?.limit,
+        fuzzy: options?.fuzzy,
+    }),
+    hybridSearch: (collection, query_text, query_vector, limit) => ({
+        type: "HybridSearch",
+        collection,
+        query_text,
+        query_vector,
+        limit,
+    }),
+    chat: (messages, model, temperature, max_tokens) => ({
+        type: "Chat",
+        messages,
+        model,
+        temperature,
+        max_tokens,
+    }),
+    embed: (input_field, output_field, model) => ({
+        type: "Embed",
+        input_field,
+        output_field,
+        model,
+    }),
+};

package/dist/index.d.ts

@@ -3,7 +3,9 @@ export { QueryBuilder, SortOrder } from "./query-builder";
 export { SearchQueryBuilder } from "./search";
 export { SchemaBuilder, FieldTypeSchemaBuilder, VectorIndexAlgorithm, DistanceMetric, } from "./schema";
 export { JoinBuilder } from "./join";
+export { Stage, ChatMessage } from "./functions";
 export type { SearchQuery, SearchResult, SearchResponse } from "./search";
 export type { Schema, FieldTypeSchema, IndexConfig, CollectionMetadata, } from "./schema";
 export type { JoinConfig } from "./join";
+export type { Script, ParameterDefinition, FunctionStageConfig, GroupFunctionConfig, SortFieldConfig, FunctionResult, FunctionStats, StageStats, } from "./functions";
 export type { Record, Query, BatchOperationResult, ClientConfig, RateLimitInfo, CollectionConfig, ChatRequest, CreateChatSessionRequest, ChatMessageRequest, TokenUsage, ChatResponse, ChatSession, ChatSessionResponse, ListSessionsQuery, ListSessionsResponse, GetMessagesQuery, GetMessagesResponse, UpdateSessionRequest, MergeSessionsRequest, } from "./client";