@ekodb/ekodb-client 0.7.0 → 0.8.0

package/dist/client.d.ts

@@ -2,7 +2,7 @@
  * ekoDB TypeScript Client
  */
 import { QueryBuilder } from "./query-builder";
-import { SearchQuery, SearchQueryBuilder, SearchResponse } from "./search";
+import { SearchQuery, SearchResponse } from "./search";
 import { Schema, SchemaBuilder, CollectionMetadata } from "./schema";
 import { Script, FunctionResult } from "./functions";
 export interface Record {
@@ -64,6 +64,52 @@ export interface BatchOperationResult {
         error: string;
     }>;
 }
+export interface InsertOptions {
+    ttl?: string;
+    bypassRipple?: boolean;
+    transactionId?: string;
+    bypassCache?: boolean;
+}
+export interface UpdateOptions {
+    bypassRipple?: boolean;
+    transactionId?: string;
+    bypassCache?: boolean;
+    selectFields?: string[];
+    excludeFields?: string[];
+}
+export interface DeleteOptions {
+    bypassRipple?: boolean;
+    transactionId?: string;
+}
+export interface UpsertOptions {
+    ttl?: string;
+    bypassRipple?: boolean;
+    transactionId?: string;
+    bypassCache?: boolean;
+}
+export interface FindOptions {
+    filter?: any;
+    sort?: any;
+    limit?: number;
+    skip?: number;
+    join?: any;
+    bypassRipple?: boolean;
+    bypassCache?: boolean;
+    selectFields?: string[];
+    excludeFields?: string[];
+}
+export interface BatchInsertOptions {
+    bypassRipple?: boolean;
+    transactionId?: string;
+}
+export interface BatchUpdateOptions {
+    bypassRipple?: boolean;
+    transactionId?: string;
+}
+export interface BatchDeleteOptions {
+    bypassRipple?: boolean;
+    transactionId?: string;
+}
 export interface CollectionConfig {
     collection_name: string;
     fields?: string[];
@@ -208,9 +254,9 @@ export declare class EkoDBClient {
      * Insert a document into a collection
      * @param collection - Collection name
      * @param record - Document to insert
-     * @param ttl - Optional TTL: duration string ("1h", "30m"), seconds ("3600"), or ISO8601 timestamp
+     * @param options - Optional parameters (ttl, bypassRipple, transactionId, bypassCache)
      */
-    insert(collection: string, record: Record, ttl?: string): Promise<Record>;
+    insert(collection: string, record: Record, options?: InsertOptions): Promise<Record>;
     /**
      * Find documents in a collection
      *
@@ -237,19 +283,29 @@ export declare class EkoDBClient {
     /**
      * Find a document by ID
      */
-    findByID(collection: string, id: string): Promise<Record>;
+    findById(collection: string, id: string): Promise<Record>;
     /**
      * Update a document
+     * @param collection - Collection name
+     * @param id - Document ID
+     * @param record - Update data
+     * @param options - Optional parameters (bypassRipple, transactionId, bypassCache, selectFields, excludeFields)
      */
-    update(collection: string, id: string, record: Record): Promise<Record>;
+    update(collection: string, id: string, record: Record, options?: UpdateOptions): Promise<Record>;
     /**
      * Delete a document
+     * @param collection - Collection name
+     * @param id - Document ID
+     * @param options - Optional parameters (bypassRipple, transactionId)
      */
-    delete(collection: string, id: string): Promise<void>;
+    delete(collection: string, id: string, options?: DeleteOptions): Promise<void>;
     /**
      * Batch insert multiple documents
+     * @param collection - Collection name
+     * @param records - Array of documents to insert
+     * @param options - Optional parameters (bypassRipple, transactionId)
      */
-    batchInsert(collection: string, records: Record[], bypassRipple?: boolean): Promise<BatchOperationResult>;
+    batchInsert(collection: string, records: Record[], options?: BatchInsertOptions): Promise<BatchOperationResult>;
     /**
      * Batch update multiple documents
      */
@@ -324,6 +380,90 @@ export declare class EkoDBClient {
      * @param transactionId - The transaction ID to rollback
      */
     rollbackTransaction(transactionId: string): Promise<void>;
+    /**
+     * Insert or update a record (upsert operation)
+     *
+     * Attempts to update the record first. If the record doesn't exist (404 error),
+     * it will be inserted instead. This provides atomic insert-or-update semantics.
+     *
+     * @param collection - Collection name
+     * @param id - Record ID
+     * @param record - Record data to insert or update
+     * @param bypassRipple - Optional flag to bypass ripple effects
+     * @returns The inserted or updated record
+     *
+     * @example
+     * ```typescript
+     * const record = { name: "John Doe", email: "john@example.com" };
+     * // Will update if exists, insert if not
+     * const result = await client.upsert("users", "user123", record);
+     * ```
+     */
+    /**
+     * Upsert a document (insert or update)
+     * @param collection - Collection name
+     * @param id - Document ID
+     * @param record - Document data
+     * @param options - Optional parameters (ttl, bypassRipple, transactionId, bypassCache)
+     */
+    upsert(collection: string, id: string, record: Record, options?: UpsertOptions): Promise<Record>;
+    /**
+     * Find a single record by field value
+     *
+     * Convenience method for finding one record matching a specific field value.
+     * Returns null if no record matches, or the first matching record.
+     *
+     * @param collection - Collection name
+     * @param field - Field name to search
+     * @param value - Value to match
+     * @returns The matching record or null if not found
+     *
+     * @example
+     * ```typescript
+     * // Find user by email
+     * const user = await client.findOne("users", "email", "john@example.com");
+     * if (user) {
+     *   console.log("Found user:", user);
+     * }
+     * ```
+     */
+    findOne(collection: string, field: string, value: any): Promise<Record | null>;
+    /**
+     * Check if a record exists by ID
+     *
+     * This is more efficient than fetching the record when you only need to check existence.
+     *
+     * @param collection - Collection name
+     * @param id - Record ID to check
+     * @returns true if the record exists, false if it doesn't
+     *
+     * @example
+     * ```typescript
+     * if (await client.exists("users", "user123")) {
+     *   console.log("User exists");
+     * } else {
+     *   console.log("User not found");
+     * }
+     * ```
+     */
+    exists(collection: string, id: string): Promise<boolean>;
+    /**
+     * Paginate through records
+     *
+     * Convenience method for pagination with page numbers (1-indexed).
+     *
+     * @param collection - Collection name
+     * @param page - Page number (1-indexed, i.e., first page is 1)
+     * @param pageSize - Number of records per page
+     * @returns Array of records for the requested page
+     *
+     * @example
+     * ```typescript
+     * // Get page 2 with 10 records per page
+     * const records = await client.paginate("users", 2, 10);
+     * ```
+     */
+    paginate(collection: string, page: number, pageSize: number): Promise<Record[]>;
     /**
      * List all collections
      */
@@ -332,6 +472,25 @@ export declare class EkoDBClient {
      * Delete a collection
      */
     deleteCollection(collection: string): Promise<void>;
+    /**
+     * Restore a deleted record from trash
+     * Records remain in trash for 30 days before permanent deletion
+     *
+     * @param collection - Collection name
+     * @param id - Record ID to restore
+     * @returns true if restored successfully
+     */
+    restoreRecord(collection: string, id: string): Promise<boolean>;
+    /**
+     * Restore all deleted records in a collection from trash
+     * Records remain in trash for 30 days before permanent deletion
+     *
+     * @param collection - Collection name
+     * @returns Number of records restored
+     */
+    restoreCollection(collection: string): Promise<{
+        recordsRestored: number;
+    }>;
     /**
      * Create a collection with schema
      *
@@ -396,7 +555,11 @@ export declare class EkoDBClient {
      * );
      * ```
      */
-    search(collection: string, searchQuery: SearchQuery | SearchQueryBuilder): Promise<SearchResponse>;
+    search(collection: string, query: SearchQuery): Promise<SearchResponse>;
+    /**
+     * Health check - verify the ekoDB server is responding
+     */
+    health(): Promise<boolean>;
     /**
      * Create a new chat session
      */
@@ -508,20 +671,24 @@ export declare class EkoDBClient {
      * 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
+     * @param query - Search query text
+     * @param options - Additional search options
+     * @returns Search response with results and metadata
      *
      * @example
      * ```typescript
      * const results = await client.textSearch(
      *   "documents",
      *   "ownership system",
-     *   10
+     *   {
+     *     limit: 10,
+     *     select_fields: ["title", "content"],
+     *     exclude_fields: ["author"]
+     *   }
      * );
      * ```
      */
-    textSearch(collection: string, queryText: string, limit: number): Promise<Record[]>;
+    textSearch(collection: string, query: string, options?: Partial<SearchQuery>): Promise<SearchResponse>;
     /**
      * Perform hybrid search combining text and vector search
      *

package/dist/client.js

@@ -39,7 +39,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 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
@@ -121,7 +120,17 @@ class EkoDBClient {
             body: JSON.stringify({ api_key: this.apiKey }),
         });
         if (!response.ok) {
-            throw new Error(`Auth failed with status: ${response.status}`);
+            let errorMsg = `Auth failed with status: ${response.status}`;
+            try {
+                const errorBody = (await response.json());
+                if (errorBody.error) {
+                    errorMsg = errorBody.error;
+                }
+            }
+            catch {
+                // Ignore JSON parse errors, use default message
+            }
+            throw new Error(errorMsg);
         }
         const result = (await response.json());
         this.token = result.token;
@@ -265,14 +274,24 @@ class EkoDBClient {
      * Insert a document into a collection
      * @param collection - Collection name
      * @param record - Document to insert
-     * @param ttl - Optional TTL: duration string ("1h", "30m"), seconds ("3600"), or ISO8601 timestamp
+     * @param options - Optional parameters (ttl, bypassRipple, transactionId, bypassCache)
      */
-    async insert(collection, record, ttl) {
+    async insert(collection, record, options) {
         const data = { ...record };
-        if (ttl) {
-            data.ttl = ttl;
+        if (options?.ttl) {
+            data.ttl = options.ttl;
         }
-        return this.makeRequest("POST", `/api/insert/${collection}`, data);
+        const params = new URLSearchParams();
+        if (options?.bypassRipple !== undefined) {
+            params.append("bypass_ripple", String(options.bypassRipple));
+        }
+        if (options?.transactionId) {
+            params.append("transaction_id", options.transactionId);
+        }
+        const url = params.toString()
+            ? `/api/insert/${collection}?${params.toString()}`
+            : `/api/insert/${collection}`;
+        return this.makeRequest("POST", url, data);
     }
     /**
      * Find documents in a collection
@@ -303,30 +322,67 @@ class EkoDBClient {
     /**
      * Find a document by ID
      */
-    async findByID(collection, id) {
+    async findById(collection, id) {
         return this.makeRequest("GET", `/api/find/${collection}/${id}`);
     }
     /**
      * Update a document
+     * @param collection - Collection name
+     * @param id - Document ID
+     * @param record - Update data
+     * @param options - Optional parameters (bypassRipple, transactionId, bypassCache, selectFields, excludeFields)
      */
-    async update(collection, id, record) {
-        return this.makeRequest("PUT", `/api/update/${collection}/${id}`, record);
+    async update(collection, id, record, options) {
+        const params = new URLSearchParams();
+        if (options?.bypassRipple !== undefined) {
+            params.append("bypass_ripple", String(options.bypassRipple));
+        }
+        if (options?.transactionId) {
+            params.append("transaction_id", options.transactionId);
+        }
+        const url = params.toString()
+            ? `/api/update/${collection}/${id}?${params.toString()}`
+            : `/api/update/${collection}/${id}`;
+        return this.makeRequest("PUT", url, record);
     }
     /**
      * Delete a document
+     * @param collection - Collection name
+     * @param id - Document ID
+     * @param options - Optional parameters (bypassRipple, transactionId)
      */
-    async delete(collection, id) {
-        await this.makeRequest("DELETE", `/api/delete/${collection}/${id}`);
+    async delete(collection, id, options) {
+        const params = new URLSearchParams();
+        if (options?.bypassRipple !== undefined) {
+            params.append("bypass_ripple", String(options.bypassRipple));
+        }
+        if (options?.transactionId) {
+            params.append("transaction_id", options.transactionId);
+        }
+        const url = params.toString()
+            ? `/api/delete/${collection}/${id}?${params.toString()}`
+            : `/api/delete/${collection}/${id}`;
+        await this.makeRequest("DELETE", url);
     }
     /**
      * Batch insert multiple documents
+     * @param collection - Collection name
+     * @param records - Array of documents to insert
+     * @param options - Optional parameters (bypassRipple, transactionId)
      */
-    async batchInsert(collection, records, bypassRipple) {
-        const inserts = records.map((data) => ({
-            data,
-            bypass_ripple: bypassRipple,
-        }));
-        return this.makeRequest("POST", `/api/batch/insert/${collection}`, { inserts });
+    async batchInsert(collection, records, options) {
+        const params = new URLSearchParams();
+        if (options?.bypassRipple !== undefined) {
+            params.append("bypass_ripple", String(options.bypassRipple));
+        }
+        if (options?.transactionId) {
+            params.append("transaction_id", options.transactionId);
+        }
+        const inserts = records.map((data) => ({ data }));
+        const url = params.toString()
+            ? `/api/batch/insert/${collection}?${params.toString()}`
+            : `/api/batch/insert/${collection}`;
+        return this.makeRequest("POST", url, { inserts });
     }
     /**
      * Batch update multiple documents
@@ -438,6 +494,139 @@ class EkoDBClient {
     async rollbackTransaction(transactionId) {
         await this.makeRequest("POST", `/api/transactions/${encodeURIComponent(transactionId)}/rollback`, undefined, 0, true);
     }
+    // ============================================================================
+    // Convenience Methods
+    // ============================================================================
+    /**
+     * Insert or update a record (upsert operation)
+     *
+     * Attempts to update the record first. If the record doesn't exist (404 error),
+     * it will be inserted instead. This provides atomic insert-or-update semantics.
+     *
+     * @param collection - Collection name
+     * @param id - Record ID
+     * @param record - Record data to insert or update
+     * @param bypassRipple - Optional flag to bypass ripple effects
+     * @returns The inserted or updated record
+     *
+     * @example
+     * ```typescript
+     * const record = { name: "John Doe", email: "john@example.com" };
+     * // Will update if exists, insert if not
+     * const result = await client.upsert("users", "user123", record);
+     * ```
+     */
+    /**
+     * Upsert a document (insert or update)
+     * @param collection - Collection name
+     * @param id - Document ID
+     * @param record - Document data
+     * @param options - Optional parameters (ttl, bypassRipple, transactionId, bypassCache)
+     */
+    async upsert(collection, id, record, options) {
+        try {
+            // Try update first
+            return await this.update(collection, id, record, {
+                bypassRipple: options?.bypassRipple,
+                transactionId: options?.transactionId,
+                bypassCache: options?.bypassCache,
+            });
+        }
+        catch (error) {
+            // If not found, insert instead
+            if (error.message?.includes("404") ||
+                error.message?.includes("Not found")) {
+                return await this.insert(collection, record, {
+                    ttl: options?.ttl,
+                    bypassRipple: options?.bypassRipple,
+                    transactionId: options?.transactionId,
+                    bypassCache: options?.bypassCache,
+                });
+            }
+            throw error;
+        }
+    }
+    /**
+     * Find a single record by field value
+     *
+     * Convenience method for finding one record matching a specific field value.
+     * Returns null if no record matches, or the first matching record.
+     *
+     * @param collection - Collection name
+     * @param field - Field name to search
+     * @param value - Value to match
+     * @returns The matching record or null if not found
+     *
+     * @example
+     * ```typescript
+     * // Find user by email
+     * const user = await client.findOne("users", "email", "john@example.com");
+     * if (user) {
+     *   console.log("Found user:", user);
+     * }
+     * ```
+     */
+    async findOne(collection, field, value) {
+        const query = new query_builder_1.QueryBuilder().eq(field, value).limit(1).build();
+        const results = await this.find(collection, query);
+        return results.length > 0 ? results[0] : null;
+    }
+    /**
+     * Check if a record exists by ID
+     *
+     * This is more efficient than fetching the record when you only need to check existence.
+     *
+     * @param collection - Collection name
+     * @param id - Record ID to check
+     * @returns true if the record exists, false if it doesn't
+     *
+     * @example
+     * ```typescript
+     * if (await client.exists("users", "user123")) {
+     *   console.log("User exists");
+     * } else {
+     *   console.log("User not found");
+     * }
+     * ```
+     */
+    async exists(collection, id) {
+        try {
+            await this.findById(collection, id);
+            return true;
+        }
+        catch (error) {
+            if (error.message?.includes("404") ||
+                error.message?.includes("Not found")) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Paginate through records
+     *
+     * Convenience method for pagination with page numbers (1-indexed).
+     *
+     * @param collection - Collection name
+     * @param page - Page number (1-indexed, i.e., first page is 1)
+     * @param pageSize - Number of records per page
+     * @returns Array of records for the requested page
+     *
+     * @example
+     * ```typescript
+     * // Get page 2 with 10 records per page
+     * const records = await client.paginate("users", 2, 10);
+     * ```
+     */
+    async paginate(collection, page, pageSize) {
+        // Page 1 = skip 0, Page 2 = skip pageSize, etc.
+        const skip = page > 0 ? (page - 1) * pageSize : 0;
+        const query = {
+            limit: pageSize,
+            skip: skip,
+        };
+        return this.find(collection, query);
+    }
     /**
      * List all collections
      */
@@ -451,6 +640,29 @@ class EkoDBClient {
     async deleteCollection(collection) {
         await this.makeRequest("DELETE", `/api/collections/${collection}`, undefined, 0, true);
     }
+    /**
+     * Restore a deleted record from trash
+     * Records remain in trash for 30 days before permanent deletion
+     *
+     * @param collection - Collection name
+     * @param id - Record ID to restore
+     * @returns true if restored successfully
+     */
+    async restoreRecord(collection, id) {
+        const result = await this.makeRequest("POST", `/api/trash/${collection}/${id}`, undefined, 0, true);
+        return result.status === "restored";
+    }
+    /**
+     * Restore all deleted records in a collection from trash
+     * Records remain in trash for 30 days before permanent deletion
+     *
+     * @param collection - Collection name
+     * @returns Number of records restored
+     */
+    async restoreCollection(collection) {
+        const result = await this.makeRequest("POST", `/api/trash/${collection}`, undefined, 0, true);
+        return { recordsRestored: result.records_restored };
+    }
     /**
      * Create a collection with schema
      *
@@ -523,11 +735,21 @@ class EkoDBClient {
      * );
      * ```
      */
-    async search(collection, searchQuery) {
-        const queryObj = searchQuery instanceof search_1.SearchQueryBuilder
-            ? searchQuery.build()
-            : searchQuery;
-        return this.makeRequest("POST", `/api/search/${collection}`, queryObj, 0, true);
+    async search(collection, query) {
+        // Ensure all parameters from SearchQuery are sent to server
+        return this.makeRequest("POST", `/api/search/${collection}`, query, 0, true);
+    }
+    /**
+     * Health check - verify the ekoDB server is responding
+     */
+    async health() {
+        try {
+            const result = await this.makeRequest("GET", "/api/health", undefined, 0, true);
+            return result.status === "ok";
+        }
+        catch {
+            return false;
+        }
     }
     // ========== Chat Methods ==========
     /**
@@ -752,26 +974,29 @@ class EkoDBClient {
      * 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
+     * @param query - Search query text
+     * @param options - Additional search options
+     * @returns Search response with results and metadata
      *
      * @example
      * ```typescript
      * const results = await client.textSearch(
      *   "documents",
      *   "ownership system",
-     *   10
+     *   {
+     *     limit: 10,
+     *     select_fields: ["title", "content"],
+     *     exclude_fields: ["author"]
+     *   }
      * );
      * ```
      */
-    async textSearch(collection, queryText, limit) {
+    async textSearch(collection, query, options) {
         const searchQuery = {
-            query: queryText,
-            limit,
+            query,
+            ...options,
         };
-        const response = await this.search(collection, searchQuery);
-        return response.results.map((r) => r.record);
+        return this.search(collection, searchQuery);
     }
     /**
      * Perform hybrid search combining text and vector search

package/dist/client.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Unit tests for ekoDB TypeScript client
+ *
+ * These tests use vitest and mock fetch to test client methods
+ * without requiring a running ekoDB server.
+ */
+export {};