@ekodb/ekodb-client 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.JoinBuilder = exports.DistanceMetric = exports.VectorIndexAlgorithm = exports.FieldTypeSchemaBuilder = exports.SchemaBuilder = exports.SearchQueryBuilder = exports.SortOrder = exports.QueryBuilder = exports.RateLimitError = exports.MergeStrategy = exports.SerializationFormat = exports.WebSocketClient = exports.EkoDBClient = void 0;
+exports.ChatMessage = exports.Stage = exports.JoinBuilder = exports.DistanceMetric = exports.VectorIndexAlgorithm = exports.FieldTypeSchemaBuilder = exports.SchemaBuilder = exports.SearchQueryBuilder = exports.SortOrder = exports.QueryBuilder = exports.RateLimitError = exports.MergeStrategy = exports.SerializationFormat = exports.WebSocketClient = exports.EkoDBClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "EkoDBClient", { enumerable: true, get: function () { return client_1.EkoDBClient; } });
 Object.defineProperty(exports, "WebSocketClient", { enumerable: true, get: function () { return client_1.WebSocketClient; } });
@@ -19,3 +19,6 @@ Object.defineProperty(exports, "VectorIndexAlgorithm", { enumerable: true, get:
 Object.defineProperty(exports, "DistanceMetric", { enumerable: true, get: function () { return schema_1.DistanceMetric; } });
 var join_1 = require("./join");
 Object.defineProperty(exports, "JoinBuilder", { enumerable: true, get: function () { return join_1.JoinBuilder; } });
+var functions_1 = require("./functions");
+Object.defineProperty(exports, "Stage", { enumerable: true, get: function () { return functions_1.Stage; } });
+Object.defineProperty(exports, "ChatMessage", { enumerable: true, get: function () { return functions_1.ChatMessage; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekodb/ekodb-client",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Official TypeScript/JavaScript client for ekoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/client.ts

@@ -6,6 +6,7 @@ import { encode, decode } from "@msgpack/msgpack";
 import { QueryBuilder, Query as QueryBuilderQuery } 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;
@@ -396,6 +397,14 @@ export 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<T>(method, path, data, attempt + 1, forceJson);
+      }
+
       // Handle service unavailable (503)
       if (
         response.status === 503 &&
@@ -954,12 +963,242 @@ export class EkoDBClient {
     );
   }
 
+  // ========================================================================
+  // SCRIPTS API
+  // ========================================================================
+
+  /**
+   * Save a new script definition
+   */
+  async saveScript(script: Script): Promise<string> {
+    const result = await this.makeRequest<{ id: string }>(
+      "POST",
+      "/api/functions",
+      script,
+    );
+    return result.id;
+  }
+
+  /**
+   * Get a script by ID
+   */
+  async getScript(id: string): Promise<Script> {
+    return this.makeRequest<Script>("GET", `/api/functions/${id}`);
+  }
+
+  /**
+   * List all scripts, optionally filtered by tags
+   */
+  async listScripts(tags?: string[]): Promise<Script[]> {
+    const params = tags ? `?tags=${tags.join(",")}` : "";
+    return this.makeRequest<Script[]>("GET", `/api/functions${params}`);
+  }
+
+  /**
+   * Update an existing script by ID
+   */
+  async updateScript(id: string, script: Script): Promise<void> {
+    await this.makeRequest<void>("PUT", `/api/functions/${id}`, script);
+  }
+
+  /**
+   * Delete a script by ID
+   */
+  async deleteScript(id: string): Promise<void> {
+    await this.makeRequest<void>("DELETE", `/api/functions/${id}`);
+  }
+
+  /**
+   * Call a saved script by ID or label
+   */
+  async callScript(
+    idOrLabel: string,
+    params?: { [key: string]: any },
+  ): Promise<FunctionResult> {
+    return this.makeRequest<FunctionResult>(
+      "POST",
+      `/api/functions/${idOrLabel}`,
+      params || {},
+    );
+  }
+
   /**
    * Create a WebSocket client
    */
   websocket(wsURL: string): WebSocketClient {
     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: string, model: string): Promise<number[]> {
+    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: 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,
+          } as any,
+        ],
+        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 as number[];
+        }
+      }
+
+      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: string,
+    queryText: string,
+    limit: number,
+  ): Promise<Record[]> {
+    const searchQuery: 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: string,
+    queryText: string,
+    queryVector: number[],
+    limit: number,
+  ): Promise<Record[]> {
+    const searchQuery: 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: string, limit: number): Promise<Record[]> {
+    const query = new QueryBuilder().limit(limit).build();
+    const results = await this.find(collection, query);
+    return results;
+  }
 }
 
 /**

package/src/functions.ts

@@ -0,0 +1,420 @@
+/**
+ * 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;
+}
+
+// ParameterValue removed - use plain values instead
+
+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 const ChatMessage = {
+  system: (content: string): ChatMessage => ({
+    role: "system",
+    content: content,
+  }),
+  user: (content: string): ChatMessage => ({
+    role: "user",
+    content: content,
+  }),
+  assistant: (content: string): ChatMessage => ({
+    role: "assistant",
+    content: content,
+  }),
+};
+
+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;
+}
+
+// Stage builder functions
+export const Stage = {
+  findAll: (collection: string): FunctionStageConfig => ({
+    type: "FindAll",
+    collection,
+  }),
+
+  query: (
+    collection: string,
+    filter?: Record<string, any>,
+    sort?: SortFieldConfig[],
+    limit?: number,
+    skip?: number,
+  ): FunctionStageConfig => ({
+    type: "Query",
+    collection,
+    filter,
+    sort,
+    limit,
+    skip,
+  }),
+
+  project: (fields: string[], exclude = false): FunctionStageConfig => ({
+    type: "Project",
+    fields,
+    exclude,
+  }),
+
+  group: (
+    by_fields: string[],
+    functions: GroupFunctionConfig[],
+  ): FunctionStageConfig => ({
+    type: "Group",
+    by_fields,
+    functions,
+  }),
+
+  count: (output_field = "count"): FunctionStageConfig => ({
+    type: "Count",
+    output_field,
+  }),
+
+  insert: (
+    collection: string,
+    record: Record<string, any>,
+    bypassRipple = false,
+    ttl?: number,
+  ): FunctionStageConfig => ({
+    type: "Insert",
+    collection,
+    record,
+    bypass_ripple: bypassRipple,
+    ttl,
+  }),
+
+  update: (
+    collection: string,
+    filter: Record<string, any>,
+    updates: Record<string, any>,
+    bypassRipple = false,
+    ttl?: number,
+  ): FunctionStageConfig => ({
+    type: "Update",
+    collection,
+    filter,
+    updates,
+    bypass_ripple: bypassRipple,
+    ttl,
+  }),
+
+  updateById: (
+    collection: string,
+    record_id: string,
+    updates: Record<string, any>,
+    bypassRipple = false,
+    ttl?: number,
+  ): FunctionStageConfig => ({
+    type: "UpdateById",
+    collection,
+    record_id,
+    updates,
+    bypass_ripple: bypassRipple,
+    ttl,
+  }),
+
+  delete: (
+    collection: string,
+    filter: Record<string, any>,
+    bypassRipple = false,
+  ): FunctionStageConfig => ({
+    type: "Delete",
+    collection,
+    filter,
+    bypass_ripple: bypassRipple,
+  }),
+
+  deleteById: (
+    collection: string,
+    record_id: string,
+    bypassRipple = false,
+  ): FunctionStageConfig => ({
+    type: "DeleteById",
+    collection,
+    record_id,
+    bypass_ripple: bypassRipple,
+  }),
+
+  batchInsert: (
+    collection: string,
+    records: Record<string, any>[],
+    bypassRipple = false,
+  ): FunctionStageConfig => ({
+    type: "BatchInsert",
+    collection,
+    records,
+    bypass_ripple: bypassRipple,
+  }),
+
+  batchDelete: (
+    collection: string,
+    record_ids: string[],
+    bypassRipple = false,
+  ): FunctionStageConfig => ({
+    type: "BatchDelete",
+    collection,
+    record_ids,
+    bypass_ripple: bypassRipple,
+  }),
+
+  filter: (filter: Record<string, any>): FunctionStageConfig => ({
+    type: "Filter",
+    filter,
+  }),
+
+  sort: (sort: SortFieldConfig[]): FunctionStageConfig => ({
+    type: "Sort",
+    sort,
+  }),
+
+  limit: (limit: number): FunctionStageConfig => ({
+    type: "Limit",
+    limit,
+  }),
+
+  skip: (skip: number): FunctionStageConfig => ({
+    type: "Skip",
+    skip,
+  }),
+
+  httpRequest: (
+    url: string,
+    method = "GET",
+    headers?: Record<string, string>,
+    body?: any,
+  ): FunctionStageConfig => ({
+    type: "HttpRequest",
+    url,
+    method,
+    headers,
+    body,
+  }),
+
+  vectorSearch: (
+    collection: string,
+    query_vector: number[],
+    limit?: number,
+    threshold?: number,
+  ): FunctionStageConfig => ({
+    type: "VectorSearch",
+    collection,
+    query_vector,
+    limit,
+    threshold,
+  }),
+
+  textSearch: (
+    collection: string,
+    query_text: string,
+    options?: { fields?: string[]; limit?: number; fuzzy?: boolean },
+  ): FunctionStageConfig => ({
+    type: "TextSearch",
+    collection,
+    query_text,
+    fields: options?.fields,
+    limit: options?.limit,
+    fuzzy: options?.fuzzy,
+  }),
+
+  hybridSearch: (
+    collection: string,
+    query_text: string,
+    query_vector?: number[],
+    limit?: number,
+  ): FunctionStageConfig => ({
+    type: "HybridSearch",
+    collection,
+    query_text,
+    query_vector,
+    limit,
+  }),
+
+  chat: (
+    messages: ChatMessage[],
+    model?: string,
+    temperature?: number,
+    max_tokens?: number,
+  ): FunctionStageConfig => ({
+    type: "Chat",
+    messages,
+    model,
+    temperature,
+    max_tokens,
+  }),
+
+  embed: (
+    input_field: string,
+    output_field: string,
+    model?: string,
+  ): FunctionStageConfig => ({
+    type: "Embed",
+    input_field,
+    output_field,
+    model,
+  }),
+};