@ekodb/ekodb-client 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,404 @@
+/**
+ * ekoDB TypeScript Client
+ */
+import { QueryBuilder } from './query-builder';
+import { SearchQuery, SearchQueryBuilder, SearchResponse } from './search';
+import { Schema, SchemaBuilder, CollectionMetadata } from './schema';
+export interface Record {
+    [key: string]: any;
+}
+/**
+ * Rate limit information from the server
+ */
+export interface RateLimitInfo {
+    /** Maximum requests allowed per window */
+    limit: number;
+    /** Requests remaining in current window */
+    remaining: number;
+    /** Unix timestamp when the rate limit resets */
+    reset: number;
+}
+/**
+ * Client configuration options
+ */
+export interface ClientConfig {
+    /** Base URL of the ekoDB server */
+    baseURL: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Enable automatic retries for rate limiting and transient errors (default: true) */
+    shouldRetry?: boolean;
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Rate limit error
+ */
+export declare class RateLimitError extends Error {
+    retryAfterSecs: number;
+    constructor(retryAfterSecs: number, message?: string);
+}
+export interface Query {
+    limit?: number;
+    offset?: number;
+    filter?: Record;
+}
+export interface BatchOperationResult {
+    successful: string[];
+    failed: Array<{
+        id?: string;
+        error: string;
+    }>;
+}
+export interface CollectionConfig {
+    collection_name: string;
+    fields?: string[];
+    search_options?: any;
+}
+export interface ChatRequest {
+    collections: CollectionConfig[];
+    llm_provider: string;
+    llm_model?: string;
+    message: string;
+    system_prompt?: string;
+    bypass_ripple?: boolean;
+}
+export interface CreateChatSessionRequest {
+    collections: CollectionConfig[];
+    llm_provider: string;
+    llm_model?: string;
+    system_prompt?: string;
+    bypass_ripple?: boolean;
+    parent_id?: string;
+    branch_point_idx?: number;
+    max_context_messages?: number;
+}
+export interface ChatMessageRequest {
+    message: string;
+    bypass_ripple?: boolean;
+    force_summarize?: boolean;
+}
+export interface TokenUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+export interface ChatResponse {
+    chat_id: string;
+    message_id: string;
+    responses: string[];
+    context_snippets: any[];
+    execution_time_ms: number;
+    token_usage?: TokenUsage;
+}
+export interface ChatSession {
+    chat_id: string;
+    created_at: string;
+    updated_at: string;
+    llm_provider: string;
+    llm_model: string;
+    collections: CollectionConfig[];
+    system_prompt?: string;
+    title?: string;
+    message_count: number;
+}
+export interface ChatSessionResponse {
+    session: Record;
+    message_count: number;
+}
+export interface ListSessionsQuery {
+    limit?: number;
+    skip?: number;
+    sort?: string;
+}
+export interface ListSessionsResponse {
+    sessions: ChatSession[];
+    total: number;
+    returned: number;
+    skip: number;
+    limit?: number;
+}
+export interface GetMessagesQuery {
+    limit?: number;
+    skip?: number;
+    sort?: string;
+}
+export interface GetMessagesResponse {
+    messages: Record[];
+    total: number;
+    skip: number;
+    limit?: number;
+    returned: number;
+}
+export interface UpdateSessionRequest {
+    system_prompt?: string;
+    llm_model?: string;
+    collections?: CollectionConfig[];
+    max_context_messages?: number;
+}
+export declare enum MergeStrategy {
+    Chronological = "Chronological",
+    Summarized = "Summarized",
+    LatestOnly = "LatestOnly"
+}
+export interface MergeSessionsRequest {
+    source_chat_ids: string[];
+    target_chat_id: string;
+    merge_strategy: MergeStrategy;
+}
+export declare class EkoDBClient {
+    private baseURL;
+    private apiKey;
+    private token;
+    private shouldRetry;
+    private maxRetries;
+    private timeout;
+    private rateLimitInfo;
+    constructor(config: string | ClientConfig, apiKey?: string);
+    /**
+     * Initialize the client by getting an auth token
+     */
+    init(): Promise<void>;
+    /**
+     * Get the current rate limit information
+     */
+    getRateLimitInfo(): RateLimitInfo | null;
+    /**
+     * Check if approaching rate limit (less than 10% remaining)
+     */
+    isNearRateLimit(): boolean;
+    /**
+     * Refresh the authentication token
+     */
+    private refreshToken;
+    /**
+     * Extract rate limit information from response headers
+     */
+    private extractRateLimitInfo;
+    /**
+     * Sleep for a specified number of seconds
+     */
+    private sleep;
+    /**
+     * Make an HTTP request to the ekoDB API with retry logic
+     */
+    private makeRequest;
+    /**
+     * Insert a document into a collection
+     */
+    insert(collection: string, record: Record, ttl?: string): Promise<Record>;
+    /**
+     * Find documents in a collection
+     *
+     * @param collection - Collection name
+     * @param query - Query object or QueryBuilder instance
+     * @returns Array of matching records
+     *
+     * @example
+     * ```typescript
+     * // Using QueryBuilder
+     * const results = await client.find("users",
+     *   new QueryBuilder()
+     *     .eq("status", "active")
+     *     .gt("age", 18)
+     *     .sortDesc("created_at")
+     *     .limit(10)
+     * );
+     *
+     * // Using plain Query object
+     * const results = await client.find("users", { limit: 10 });
+     * ```
+     */
+    find(collection: string, query?: Query | QueryBuilder): Promise<Record[]>;
+    /**
+     * Find a document by ID
+     */
+    findByID(collection: string, id: string): Promise<Record>;
+    /**
+     * Update a document
+     */
+    update(collection: string, id: string, record: Record): Promise<Record>;
+    /**
+     * Delete a document
+     */
+    delete(collection: string, id: string): Promise<void>;
+    /**
+     * Batch insert multiple documents
+     */
+    batchInsert(collection: string, records: Record[]): Promise<Record[]>;
+    /**
+     * Batch update multiple documents
+     */
+    batchUpdate(collection: string, updates: Array<{
+        id: string;
+        data: Record;
+    }>): Promise<Record[]>;
+    /**
+     * Batch delete multiple documents
+     */
+    batchDelete(collection: string, ids: string[]): Promise<number>;
+    /**
+     * Set a key-value pair
+     */
+    kvSet(key: string, value: any): Promise<void>;
+    /**
+     * Get a value by key
+     */
+    kvGet(key: string): Promise<any>;
+    /**
+     * Delete a key
+     */
+    kvDelete(key: string): Promise<void>;
+    /**
+     * List all collections
+     */
+    listCollections(): Promise<string[]>;
+    /**
+     * Delete a collection
+     */
+    deleteCollection(collection: string): Promise<void>;
+    /**
+     * Create a collection with schema
+     *
+     * @param collection - Collection name
+     * @param schema - Schema definition or SchemaBuilder instance
+     *
+     * @example
+     * ```typescript
+     * const schema = new SchemaBuilder()
+     *   .addField("name", new FieldTypeSchemaBuilder("string").required())
+     *   .addField("email", new FieldTypeSchemaBuilder("string").unique())
+     *   .addField("age", new FieldTypeSchemaBuilder("number").range(0, 150));
+     *
+     * await client.createCollection("users", schema);
+     * ```
+     */
+    createCollection(collection: string, schema: Schema | SchemaBuilder): Promise<void>;
+    /**
+     * Get collection metadata and schema
+     *
+     * @param collection - Collection name
+     * @returns Collection metadata including schema and analytics
+     */
+    getCollection(collection: string): Promise<CollectionMetadata>;
+    /**
+     * Get collection schema
+     *
+     * @param collection - Collection name
+     * @returns The collection schema
+     */
+    getSchema(collection: string): Promise<Schema>;
+    /**
+     * Search documents in a collection using full-text, vector, or hybrid search
+     *
+     * @param collection - Collection name
+     * @param searchQuery - Search query object or SearchQueryBuilder instance
+     * @returns Search response with results and metadata
+     *
+     * @example
+     * ```typescript
+     * // Full-text search
+     * const results = await client.search("users",
+     *   new SearchQueryBuilder("john")
+     *     .fields(["name", "email"])
+     *     .fuzzy(true)
+     *     .limit(10)
+     * );
+     *
+     * // Vector search
+     * const results = await client.search("documents",
+     *   new SearchQueryBuilder("")
+     *     .vector([0.1, 0.2, 0.3, ...])
+     *     .vectorK(5)
+     * );
+     *
+     * // Hybrid search
+     * const results = await client.search("products",
+     *   new SearchQueryBuilder("laptop")
+     *     .vector([0.1, 0.2, ...])
+     *     .textWeight(0.7)
+     *     .vectorWeight(0.3)
+     * );
+     * ```
+     */
+    search(collection: string, searchQuery: SearchQuery | SearchQueryBuilder): Promise<SearchResponse>;
+    /**
+     * Create a new chat session
+     */
+    createChatSession(request: CreateChatSessionRequest): Promise<ChatResponse>;
+    /**
+     * Send a message in an existing chat session
+     */
+    chatMessage(sessionId: string, request: ChatMessageRequest): Promise<ChatResponse>;
+    /**
+     * Get a chat session by ID
+     */
+    getChatSession(sessionId: string): Promise<ChatSessionResponse>;
+    /**
+     * List all chat sessions
+     */
+    listChatSessions(query?: ListSessionsQuery): Promise<ListSessionsResponse>;
+    /**
+     * Get messages from a chat session
+     */
+    getChatSessionMessages(sessionId: string, query?: GetMessagesQuery): Promise<GetMessagesResponse>;
+    /**
+     * Update a chat session
+     */
+    updateChatSession(sessionId: string, request: UpdateSessionRequest): Promise<ChatSessionResponse>;
+    /**
+     * Branch a chat session
+     */
+    branchChatSession(request: CreateChatSessionRequest): Promise<ChatResponse>;
+    /**
+     * Delete a chat session
+     */
+    deleteChatSession(sessionId: string): Promise<void>;
+    /**
+     * Regenerate an AI response message
+     */
+    regenerateMessage(sessionId: string, messageId: string): Promise<ChatResponse>;
+    /**
+     * Update a specific message
+     */
+    updateChatMessage(sessionId: string, messageId: string, content: string): Promise<void>;
+    /**
+     * Delete a specific message
+     */
+    deleteChatMessage(sessionId: string, messageId: string): Promise<void>;
+    /**
+     * Toggle the "forgotten" status of a message
+     */
+    toggleForgottenMessage(sessionId: string, messageId: string, forgotten: boolean): Promise<void>;
+    /**
+     * Merge multiple chat sessions into one
+     */
+    mergeChatSessions(request: MergeSessionsRequest): Promise<ChatSessionResponse>;
+    /**
+     * Create a WebSocket client
+     */
+    websocket(wsURL: string): WebSocketClient;
+}
+/**
+ * WebSocket client for real-time queries
+ */
+export declare class WebSocketClient {
+    private wsURL;
+    private token;
+    private ws;
+    constructor(wsURL: string, token: string);
+    /**
+     * Connect to WebSocket
+     */
+    private connect;
+    /**
+     * Find all records in a collection via WebSocket
+     */
+    findAll(collection: string): Promise<Record[]>;
+    /**
+     * Close the WebSocket connection
+     */
+    close(): void;
+}