vecmindb 1.0.0-beta

package/dist/index.d.ts

@@ -0,0 +1,934 @@
+/**
+ * @module models
+ * @description TypeScript type definitions for the VecminDB SDK.
+ * Covers all API request/response types, configuration options,
+ * and data structures used across the SDK.
+ */
+/** Options for constructing a {@link VecminClient} instance. */
+interface VecminClientOptions {
+    /** Base URL of the VecminDB server (e.g. `http://localhost:8080`). */
+    baseUrl: string;
+    /** API key for authentication via `x-api-key` header. */
+    apiKey?: string;
+    /** JWT token for authentication. If provided alongside `apiKey`, JWT takes precedence on protected routes. */
+    jwt?: string;
+    /** Request timeout in milliseconds. @default 30_000 */
+    timeout?: number;
+    /** Maximum number of automatic retries on transient failures. @default 3 */
+    maxRetries?: number;
+    /** Backoff multiplier (seconds) for exponential retry delay. @default 0.5 */
+    backoffFactor?: number;
+    /** Custom HTTP headers included with every request. */
+    defaultHeaders?: Record<string, string>;
+    /** Optional agent identifier injected via `x-agent-id` header. */
+    agentId?: string;
+    /** Optional model identifier injected via `x-model-id` header. */
+    modelId?: string;
+}
+/** Standardised response envelope returned by every VecminDB API endpoint. */
+interface VecminResponse<T> {
+    /** HTTP-style status code. */
+    code: number;
+    /** Human-readable status message. */
+    message: string;
+    /** Response payload. */
+    data: T;
+}
+/** Parameters for creating a new collection. */
+interface CreateCollectionParams {
+    /** Unique name for the collection. */
+    name: string;
+    /** Dimensionality of the vectors stored in the collection. */
+    dimension: number;
+    /** Distance metric. @default "Cosine" */
+    metric_type?: MetricType;
+    /** Index algorithm. @default "HNSW" */
+    index_type?: IndexType;
+    /** Algorithm-specific parameters. */
+    index_params?: Record<string, unknown>;
+}
+/** A VecminDB collection. */
+interface Collection {
+    /** Collection name. */
+    name: string;
+    /** Vector dimensionality. */
+    dimension: number;
+    /** Distance metric used. */
+    metric_type: MetricType;
+    /** Index algorithm used. */
+    index_type: IndexType;
+    /** Index hyper-parameters. */
+    index_params: Record<string, unknown>;
+    /** Number of vectors stored. */
+    vector_count?: number;
+    /** ISO-8601 creation timestamp. */
+    created_at?: string;
+    /** ISO-8601 last-update timestamp. */
+    updated_at?: string;
+}
+/** Statistical summary of a collection. */
+interface CollectionStats {
+    /** Collection name. */
+    name: string;
+    /** Number of stored vectors. */
+    vector_count: number;
+    /** Storage consumption in bytes. */
+    storage_bytes: number;
+    /** Index build progress (0–100). */
+    index_progress?: number;
+    /** ISO-8601 creation timestamp. */
+    created_at?: string;
+}
+/** Parameters for inserting a single vector. */
+interface InsertParams {
+    /** Unique identifier for the vector. If omitted the server generates one. */
+    id?: string;
+    /** The vector embedding. */
+    vector: number[];
+    /** Arbitrary key-value metadata attached to the vector. */
+    metadata?: Record<string, unknown>;
+}
+/** Parameters for searching vectors. */
+interface SearchParams {
+    /** Query vector. */
+    query: number[];
+    /** Number of nearest neighbours to return. @default 10 */
+    k?: number;
+    /** HNSW ef-search parameter. @default 50 */
+    ef_search?: number;
+    /** Override the collection's default metric for this query. */
+    metric?: MetricType;
+    /** Metadata filter expression (server-side). */
+    filter?: Record<string, unknown>;
+}
+/** A single search result item. */
+interface SearchResult {
+    /** Vector identifier. */
+    id: string;
+    /** Similarity score (higher = more similar for cosine/inner-product). */
+    score: number;
+    /** The vector itself (may be omitted by the server for efficiency). */
+    vector?: number[];
+    /** Attached metadata. */
+    metadata?: Record<string, unknown>;
+}
+/** A stored vector record. */
+interface Vector {
+    /** Unique identifier. */
+    id: string;
+    /** The vector embedding. */
+    vector: number[];
+    /** Attached metadata. */
+    metadata?: Record<string, unknown>;
+}
+/** Index summary returned by the list-indexes endpoint. */
+interface IndexInfo {
+    /** Index name. */
+    name: string;
+    /** Algorithm used. */
+    index_type: IndexType;
+    /** Collection this index belongs to. */
+    collection: string;
+    /** Build status. */
+    status?: string;
+}
+/** Login credentials for JWT authentication. */
+interface LoginParams {
+    /** Username or API key. */
+    username: string;
+    /** Password or secret. */
+    password: string;
+}
+/** A node in the VecminDB cluster. */
+interface Node {
+    /** Unique node identifier. */
+    id: string;
+    /** Network address (host:port). */
+    address: string;
+    /** Node role. */
+    role: "leader" | "follower" | "candidate";
+    /** `true` if the node is reachable. */
+    healthy: boolean;
+}
+/** Cluster-wide status overview. */
+interface ClusterStatus {
+    /** Cluster health indicator. */
+    status: "healthy" | "degraded" | "unavailable";
+    /** Current leader node ID. */
+    leader_id: string;
+    /** Total number of nodes. */
+    node_count: number;
+    /** Number of healthy nodes. */
+    healthy_count: number;
+    /** Raft term. */
+    term?: number;
+    /** Raft commit index. */
+    commit_index?: number;
+}
+/** Options for MCP operations. */
+interface MCPOptions {
+    /** Collection to store/search memories in. @default "agent_memory_mcp" */
+    collection?: string;
+    /** Source tag for the memory. */
+    source?: string;
+    /** Embedding dimension. @default 384 */
+    dimension?: number;
+}
+/** A single MCP search result. */
+interface MCPSearchResult {
+    /** Document ID. */
+    id: string;
+    /** Similarity score. */
+    score: number;
+    /** The original text content. */
+    content: string;
+    /** Agent that stored this memory. */
+    agent_id: string;
+    /** Source tag. */
+    source?: string;
+    /** Full metadata object. */
+    metadata?: Record<string, unknown>;
+}
+/** MCP client configuration. */
+interface MCPClientOptions {
+    /** API key for authenticating MCP requests. */
+    apiKey?: string;
+    /** JWT token. */
+    jwt?: string;
+    /** Agent identifier. */
+    agentId?: string;
+    /** Model identifier. */
+    modelId?: string;
+}
+/** Parameters for the `store_memory` MCP tool. */
+interface StoreMemoryParams {
+    /** The text content to store. */
+    text: string;
+    /** Agent identifier. */
+    agent_id: string;
+    /** Source tag. */
+    source?: string;
+    /** Override target collection. */
+    collection?: string;
+}
+/** Parameters for the `search_memory` MCP tool. */
+interface SearchMemoryParams {
+    /** Natural-language query. */
+    query: string;
+    /** Agent identifier to scope the search. */
+    agent_id: string;
+    /** Number of results. @default 5 */
+    top_k?: number;
+    /** Override target collection. */
+    collection?: string;
+}
+/** JSON-RPC 2.0 request envelope. */
+interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id: number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+/** JSON-RPC 2.0 success response. */
+interface JsonRpcResponse<T = unknown> {
+    jsonrpc: "2.0";
+    id: number;
+    result?: T;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/** Options for constructing a {@link VecminDBVectorStore}. */
+interface VecminVectorStoreOptions {
+    /** VecminDB base URL. */
+    baseUrl: string;
+    /** API key. */
+    apiKey?: string;
+    /** Collection name. @default "langchain_memory" */
+    collectionName?: string;
+    /** Vector dimensionality. @default 1536 */
+    dimension?: number;
+    /** Distance metric. @default "Cosine" */
+    metricType?: MetricType;
+    /** Index type. @default "HNSW" */
+    indexType?: IndexType;
+    /** Index hyper-parameters. */
+    indexParams?: Record<string, unknown>;
+    /** Request timeout. */
+    timeout?: number;
+}
+/** Supported distance metrics. */
+type MetricType = "Cosine" | "L2" | "InnerProduct";
+/** Supported index algorithms. */
+type IndexType = "HNSW" | "IVF" | "Flat";
+/** Configuration for the retry policy. */
+interface RetryOptions {
+    /** Maximum retry attempts. @default 3 */
+    maxRetries?: number;
+    /** Backoff multiplier in seconds. @default 0.5 */
+    backoffFactor?: number;
+    /** HTTP status codes that trigger a retry. @default [429,500,502,503,504] */
+    retryableStatusCodes?: number[];
+}
+
+/**
+ * @module client
+ * @description Main VecminDB SDK client.
+ *
+ * `VecminClient` is the primary entry-point for interacting with a
+ * VecminDB server. It provides typed, async methods for every API endpoint
+ * and transparently handles authentication, retries, and response unwrapping.
+ */
+
+/**
+ * Official TypeScript client for VecminDB.
+ *
+ * @example
+ * ```ts
+ * const client = new VecminClient({ baseUrl: "http://localhost:8080", apiKey: "my-key" });
+ *
+ * await client.createCollection({ name: "docs", dimension: 1536 });
+ * const id = await client.insert("docs", { vector: [0.1, 0.2, ...], metadata: { title: "Hello" } });
+ * const results = await client.search("docs", { query: [0.1, 0.2, ...], k: 5 });
+ * ```
+ */
+declare class VecminClient {
+    /** Resolved base URL (trailing slash stripped). */
+    private readonly baseUrl;
+    /** API path prefix. */
+    private readonly apiUrl;
+    /** MCP path prefix. */
+    private readonly mcpUrl;
+    /** Authentication manager. */
+    private readonly auth;
+    /** Request timeout in milliseconds. */
+    private readonly timeout;
+    /** Retry configuration propagated to every request. */
+    private readonly retryOptions;
+    /** Default headers merged into every request. */
+    private readonly defaultHeaders;
+    /** Abort controllers for in-flight requests (used by `close()`). */
+    private readonly controllers;
+    /** Whether the client has been closed. */
+    private closed;
+    constructor(options: VecminClientOptions);
+    /** Build the full headers map for an outgoing request. */
+    private buildHeaders;
+    /** Create an AbortController with the configured timeout and track it. */
+    private createController;
+    /** Perform a JSON GET request. */
+    private get;
+    /** Perform a JSON POST request. */
+    private post;
+    /** Perform a JSON DELETE request. */
+    private del;
+    /** Throw if the client has been closed. */
+    private assertOpen;
+    /**
+     * Create a new collection.
+     *
+     * @example
+     * ```ts
+     * const col = await client.createCollection({
+     *   name: "docs",
+     *   dimension: 1536,
+     *   metric_type: "Cosine",
+     *   index_type: "HNSW",
+     * });
+     * ```
+     */
+    createCollection(params: CreateCollectionParams): Promise<Collection>;
+    /**
+     * List all collections.
+     *
+     * @example
+     * ```ts
+     * const collections = await client.listCollections();
+     * ```
+     */
+    listCollections(): Promise<Collection[]>;
+    /**
+     * Get details for a specific collection.
+     *
+     * @example
+     * ```ts
+     * const col = await client.getCollection("docs");
+     * ```
+     */
+    getCollection(name: string): Promise<Collection>;
+    /**
+     * Delete a collection and all its data.
+     *
+     * @example
+     * ```ts
+     * await client.deleteCollection("docs");
+     * ```
+     */
+    deleteCollection(name: string): Promise<void>;
+    /**
+     * Get statistics for a collection.
+     *
+     * @example
+     * ```ts
+     * const stats = await client.getCollectionStats("docs");
+     * console.log(`Vectors: ${stats.vector_count}`);
+     * ```
+     */
+    getCollectionStats(name: string): Promise<CollectionStats>;
+    /**
+     * Insert a single vector into a collection.
+     *
+     * @returns The vector ID (either the caller-supplied ID or a server-generated one).
+     *
+     * @example
+     * ```ts
+     * const id = await client.insert("docs", {
+     *   vector: [0.1, 0.2, /* ... *\/],
+     *   metadata: { title: "Hello" },
+     * });
+     * ```
+     */
+    insert(collection: string, params: InsertParams): Promise<string>;
+    /**
+     * Insert multiple vectors in a single request.
+     *
+     * @returns An array of vector IDs in the same order as the input.
+     *
+     * @example
+     * ```ts
+     * const ids = await client.batchInsert("docs", [
+     *   { vector: [0.1, 0.2], metadata: { title: "A" } },
+     *   { vector: [0.3, 0.4], metadata: { title: "B" } },
+     * ]);
+     * ```
+     */
+    batchInsert(collection: string, vectors: InsertParams[]): Promise<string[]>;
+    /**
+     * Search for the nearest neighbours of a query vector.
+     *
+     * @example
+     * ```ts
+     * const results = await client.search("docs", {
+     *   query: [0.1, 0.2, /* ... *\/],
+     *   k: 5,
+     *   ef_search: 100,
+     * });
+     * for (const r of results) {
+     *   console.log(r.id, r.score);
+     * }
+     * ```
+     */
+    search(collection: string, params: SearchParams): Promise<SearchResult[]>;
+    /**
+     * Retrieve a single vector by its ID.
+     *
+     * @example
+     * ```ts
+     * const vec = await client.getVector("docs", "abc-123");
+     * ```
+     */
+    getVector(collection: string, id: string): Promise<Vector>;
+    /**
+     * Delete a single vector by its ID.
+     *
+     * @example
+     * ```ts
+     * await client.deleteVector("docs", "abc-123");
+     * ```
+     */
+    deleteVector(collection: string, id: string): Promise<void>;
+    /**
+     * Trigger an index rebuild for a collection.
+     *
+     * @example
+     * ```ts
+     * await client.rebuildIndex("docs");
+     * ```
+     */
+    rebuildIndex(collection: string): Promise<void>;
+    /**
+     * List all indexes in the cluster.
+     *
+     * @example
+     * ```ts
+     * const indexes = await client.listIndexes();
+     * ```
+     */
+    listIndexes(): Promise<IndexInfo[]>;
+    /**
+     * Rebuild a named index.
+     *
+     * @example
+     * ```ts
+     * await client.rebuildNamedIndex("docs_hnsw");
+     * ```
+     */
+    rebuildNamedIndex(name: string): Promise<void>;
+    /**
+     * Optimize a named index.
+     *
+     * @example
+     * ```ts
+     * await client.optimizeIndex("docs_hnsw");
+     * ```
+     */
+    optimizeIndex(name: string): Promise<void>;
+    /**
+     * Authenticate and obtain a JWT token.
+     * The token is cached and automatically refreshed before expiry.
+     *
+     * @returns The JWT string.
+     *
+     * @example
+     * ```ts
+     * const jwt = await client.login({ username: "admin", password: "secret" });
+     * ```
+     */
+    login(credentials: LoginParams): Promise<string>;
+    /**
+     * List all nodes in the cluster.
+     *
+     * @example
+     * ```ts
+     * const nodes = await client.listNodes();
+     * ```
+     */
+    listNodes(): Promise<Node[]>;
+    /**
+     * Get the overall cluster status.
+     *
+     * @example
+     * ```ts
+     * const status = await client.clusterStatus();
+     * console.log(status.status, status.leader_id);
+     * ```
+     */
+    clusterStatus(): Promise<ClusterStatus>;
+    /**
+     * Create a cluster snapshot.
+     *
+     * @example
+     * ```ts
+     * await client.createSnapshot();
+     * ```
+     */
+    createSnapshot(): Promise<void>;
+    /**
+     * Store a memory via the MCP `store_memory` tool.
+     *
+     * This is a convenience wrapper that calls the MCP JSON-RPC endpoint.
+     *
+     * @example
+     * ```ts
+     * await client.mcpStoreMemory("User prefers dark mode", "agent-1");
+     * ```
+     */
+    mcpStoreMemory(text: string, agentId: string, options?: MCPOptions): Promise<void>;
+    /**
+     * Search memories via the MCP `search_memory` tool.
+     *
+     * @example
+     * ```ts
+     * const results = await client.mcpSearchMemory("user preferences", "agent-1", 5);
+     * ```
+     */
+    mcpSearchMemory(query: string, agentId: string, topK?: number): Promise<MCPSearchResult[]>;
+    /**
+     * Gracefully shut down the client.
+     * Aborts all in-flight requests and releases resources.
+     *
+     * @example
+     * ```ts
+     * await client.close();
+     * ```
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * @module mcp
+ * @description MCP (Model Context Protocol) client for VecminDB.
+ *
+ * Provides:
+ * - SSE event-stream connection (`GET /mcp/sse`)
+ * - JSON-RPC 2.0 tool invocation (`POST /mcp/messages`)
+ *
+ * The MCP protocol enables AI agents to store and retrieve memories
+ * through a standardised tool interface.
+ */
+
+/** Events emitted by {@link VecminMCPClient}. */
+type MCPEventMap = {
+    /** Fired when the SSE connection is established. */
+    connected: void;
+    /** Fired when the SSE connection is closed. */
+    disconnected: void;
+    /** Fired for each SSE event received from the server. */
+    event: {
+        event: string;
+        data: string;
+    };
+    /** Fired when a JSON-RPC response is received. */
+    result: {
+        id: number;
+        result: unknown;
+    };
+    /** Fired when an error occurs. */
+    error: Error;
+};
+type EventHandler<T> = (data: T) => void;
+/**
+ * Low-level MCP client that connects to a VecminDB server's
+ * Model Context Protocol endpoints.
+ *
+ * ### SSE (Server-Sent Events)
+ * The client opens a persistent connection to `GET /mcp/sse` and parses
+ * incoming events using the `eventsource-parser` library.
+ *
+ * ### JSON-RPC 2.0
+ * Tool invocations (`store_memory`, `search_memory`) are sent as JSON-RPC
+ * requests to `POST /mcp/messages`.
+ *
+ * @example
+ * ```ts
+ * const mcp = new VecminMCPClient("http://localhost:8080", { apiKey: "my-key" });
+ * await mcp.connect();
+ *
+ * mcp.on("event", ({ event, data }) => console.log(event, data));
+ *
+ * await mcp.storeMemory({ text: "Hello world", agent_id: "agent-1" });
+ * const results = await mcp.searchMemory({ query: "hello", agent_id: "agent-1" });
+ *
+ * await mcp.disconnect();
+ * ```
+ */
+declare class VecminMCPClient {
+    private readonly baseUrl;
+    private readonly mcpUrl;
+    private readonly options;
+    private readonly handlers;
+    private rpcId;
+    private readonly pendingRpc;
+    private abortController;
+    private reader;
+    private connected;
+    constructor(baseUrl: string, options?: MCPClientOptions);
+    /**
+     * Register an event handler.
+     *
+     * @param event   - One of the {@link MCPEventMap} keys.
+     * @param handler - Callback invoked when the event fires.
+     */
+    on<K extends keyof MCPEventMap>(event: K, handler: EventHandler<MCPEventMap[K]>): void;
+    /**
+     * Remove a previously registered event handler.
+     */
+    off<K extends keyof MCPEventMap>(event: K, handler: EventHandler<MCPEventMap[K]>): void;
+    private emit;
+    /**
+     * Open the SSE event-stream connection to `GET /mcp/sse`.
+     *
+     * The connection remains open until {@link disconnect} is called.
+     * Events are parsed and emitted via the `on("event", ...)` interface.
+     */
+    connect(): Promise<void>;
+    /**
+     * Read and parse an SSE stream using `eventsource-parser`.
+     */
+    private readSSEStream;
+    /**
+     * Send a JSON-RPC 2.0 request to `POST /mcp/messages`.
+     *
+     * @returns The `result` field of the JSON-RPC response.
+     */
+    private rpc;
+    /**
+     * Call the `store_memory` MCP tool.
+     *
+     * @example
+     * ```ts
+     * await mcp.storeMemory({ text: "User prefers dark mode", agent_id: "agent-1" });
+     * ```
+     */
+    storeMemory(params: StoreMemoryParams): Promise<void>;
+    /**
+     * Call the `search_memory` MCP tool.
+     *
+     * @example
+     * ```ts
+     * const results = await mcp.searchMemory({ query: "preferences", agent_id: "agent-1", top_k: 5 });
+     * ```
+     */
+    searchMemory(params: SearchMemoryParams): Promise<MCPSearchResult[]>;
+    /**
+     * Close the SSE connection and release all resources.
+     */
+    disconnect(): Promise<void>;
+}
+
+/**
+ * @module langchain
+ * @description LangChain.js VectorStore adapter for VecminDB.
+ *
+ * Implements the {@link VectorStore} interface from `@langchain/core`,
+ * enabling drop-in usage of VecminDB as a vector store within the
+ * LangChain.js ecosystem.
+ *
+ * **Note:** `@langchain/core` is an optional peer dependency.
+ * If it is not installed, importing this module will throw at runtime.
+ */
+
+/**
+ * LangChain.js VectorStore adapter backed by VecminDB.
+ *
+ * Extends the abstract `VectorStore` class from `@langchain/core`
+ * so it can be used anywhere LangChain expects a vector store —
+ * retrievers, chains, agents, etc.
+ *
+ * @example
+ * ```ts
+ * import { OpenAIEmbeddings } from "@langchain/openai";
+ * import { VecminDBVectorStore } from "@vecmindb/sdk/langchain";
+ *
+ * const embeddings = new OpenAIEmbeddings();
+ * const store = new VecminDBVectorStore(embeddings, {
+ *   baseUrl: "http://localhost:8080",
+ *   apiKey: "my-key",
+ *   collectionName: "my_docs",
+ *   dimension: 1536,
+ * });
+ *
+ * await store.addDocuments([
+ *   { pageContent: "Hello world", metadata: { source: "test" } },
+ * ]);
+ *
+ * const results = await store.similaritySearch("hello", 5);
+ * ```
+ */
+declare class VecminDBVectorStore {
+    /** Underlying VecminDB client used for all I/O. */
+    readonly client: VecminClient;
+    /** LangChain embeddings instance. */
+    private readonly _embeddings;
+    /** Collection name in VecminDB. */
+    private readonly collectionName;
+    /** Vector dimensionality. */
+    private readonly dimension;
+    /** Whether the collection has been ensured to exist. */
+    private ensured;
+    /** @internal */ lc_namespace: string[];
+    /** @internal */ lc_serializable: boolean;
+    constructor(embeddings: unknown, options: VecminVectorStoreOptions);
+    /**
+     * Ensure the target collection exists in VecminDB.
+     * Called lazily before the first write operation.
+     */
+    private ensureCollection;
+    /**
+     * Add documents to the vector store.
+     * Embeds the document texts and inserts them into VecminDB.
+     */
+    addDocuments(documents: Array<{
+        pageContent: string;
+        metadata: Record<string, unknown>;
+    }>): Promise<string[]>;
+    /**
+     * Add pre-computed vectors to the vector store.
+     */
+    addVectors(vectors: number[][], documents: Array<{
+        pageContent: string;
+        metadata: Record<string, unknown>;
+    }>, metadatas?: Array<Record<string, unknown>>): Promise<string[]>;
+    /**
+     * Search for the most similar vectors and return results with scores.
+     *
+     * @param query - Query vector.
+     * @param k     - Number of results. @default 4
+     */
+    similaritySearchVectorWithScore(query: number[], k?: number): Promise<Array<[{
+        pageContent: string;
+        metadata: Record<string, unknown>;
+    }, number]>>;
+    /**
+     * Convenience method: search for similar documents (without scores).
+     */
+    similaritySearch(query: string, k?: number): Promise<Array<{
+        pageContent: string;
+        metadata: Record<string, unknown>;
+    }>>;
+    /**
+     * Convenience method: search for similar documents with scores.
+     */
+    similaritySearchWithScore(query: string, k?: number): Promise<Array<[{
+        pageContent: string;
+        metadata: Record<string, unknown>;
+    }, number]>>;
+    /**
+     * Create a VecminDBVectorStore from an array of Document objects.
+     *
+     * @example
+     * ```ts
+     * const store = await VecminDBVectorStore.fromDocuments(
+     *   [{ pageContent: "Hello", metadata: {} }],
+     *   embeddings,
+     *   { baseUrl: "http://localhost:8080" },
+     * );
+     * ```
+     */
+    static fromDocuments(documents: Array<{
+        pageContent: string;
+        metadata: Record<string, unknown>;
+    }>, embeddings: unknown, options: VecminVectorStoreOptions): Promise<VecminDBVectorStore>;
+    /**
+     * Create a VecminDBVectorStore from an array of texts.
+     *
+     * @example
+     * ```ts
+     * const store = await VecminDBVectorStore.fromTexts(
+     *   ["Hello world", "Goodbye world"],
+     *   [{}, {}],
+     *   embeddings,
+     *   { baseUrl: "http://localhost:8080" },
+     * );
+     * ```
+     */
+    static fromTexts(texts: string[], metadatas: Array<Record<string, unknown>>, embeddings: unknown, options: VecminVectorStoreOptions): Promise<VecminDBVectorStore>;
+    /**
+     * Close the underlying client connection.
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * @module auth
+ * @description Authentication manager for the VecminDB SDK.
+ *
+ * Handles:
+ * - API-Key injection via the `x-api-key` header.
+ * - JWT token management with automatic refresh (5 minutes before expiry).
+ * - Token caching and thread-safe access.
+ */
+
+/**
+ * Manages authentication state for the SDK client.
+ *
+ * ### API-Key mode
+ * Injects `x-api-key: <key>` on every request.
+ *
+ * ### JWT mode
+ * Injects `Authorization: Bearer <jwt>`.
+ * When the JWT is within 5 minutes of expiry the manager automatically
+ * re-authenticates via `POST /api/v1/cluster/login`.
+ */
+declare class AuthManager {
+    private apiKey?;
+    private jwt?;
+    private loginParams?;
+    private baseUrl;
+    private refreshPromise;
+    constructor(baseUrl: string, options: VecminClientOptions);
+    /**
+     * Store login credentials so the manager can automatically refresh the JWT.
+     * Called internally by {@link VecminClient.login}.
+     */
+    setLoginCredentials(params: LoginParams, jwt: string): void;
+    /**
+     * Return the HTTP headers needed for the next request.
+     *
+     * If a JWT is present and not expiring soon, uses `Authorization: Bearer`.
+     * Otherwise falls back to `x-api-key` (if configured).
+     *
+     * When both are configured, JWT takes precedence; if the JWT is expiring
+     * the method triggers a background refresh and falls back to the API key
+     * for the current request.
+     */
+    getHeaders(): Promise<Record<string, string>>;
+    /**
+     * Attempt to refresh the JWT by re-posting the stored login credentials.
+     * Uses a singleton promise so concurrent calls don't trigger multiple logins.
+     */
+    private refreshJwt;
+}
+
+/**
+ * @module retry
+ * @description Configurable exponential-backoff retry strategy for transient failures.
+ */
+
+/**
+ * Resolve the effective retry options by merging caller-provided values
+ * with SDK defaults.
+ */
+declare function resolveRetryOptions(opts?: RetryOptions): Required<RetryOptions>;
+/**
+ * Execute an async function with exponential-backoff retry semantics.
+ *
+ * @param fn         - The async operation to attempt.
+ * @param options    - Retry configuration.
+ * @returns          - The result of `fn` on success.
+ * @throws           - The last {@link VecminError} when all retries are exhausted.
+ *
+ * @example
+ * ```ts
+ * const data = await withRetry(() => fetchJson("/api/v1/collections"), { maxRetries: 5 });
+ * ```
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Lightweight wrapper around `fetch` that:
+ * 1. Throws structured {@link VecminError} subclasses on non-2xx responses.
+ * 2. Parses the standard VecminDB response envelope `{code, message, data}`.
+ *
+ * This is the single point of HTTP I/O for the SDK.
+ */
+declare function fetchJson<T>(url: string, init: RequestInit, retryOpts?: RetryOptions): Promise<T>;
+
+/**
+ * @module errors
+ * @description Custom error hierarchy for the VecminDB SDK.
+ *
+ * Every error thrown by the SDK is a subclass of {@link VecminError},
+ * making it straightforward to catch and inspect failures.
+ */
+/**
+ * Base error class for all VecminDB SDK errors.
+ * Carries the HTTP status code for easy programmatic handling.
+ */
+declare class VecminError extends Error {
+    /** HTTP-style status code from the server response. */
+    readonly code: number;
+    constructor(message: string, code: number);
+}
+/** Thrown when the request lacks valid credentials (HTTP 401). */
+declare class AuthenticationError extends VecminError {
+    constructor(message?: string);
+}
+/** Thrown when the authenticated identity lacks the required permission (HTTP 403). */
+declare class PermissionError extends VecminError {
+    constructor(message?: string);
+}
+/** Thrown when subscription payment or a valid license key is required (HTTP 402). */
+declare class PaymentRequiredError extends VecminError {
+    constructor(message?: string);
+}
+/** Thrown when the requested resource does not exist (HTTP 404). */
+declare class NotFoundError extends VecminError {
+    constructor(message?: string);
+}
+/** Thrown when the server rate-limits the request (HTTP 429). */
+declare class RateLimitError extends VecminError {
+    constructor(message?: string);
+}
+/** Thrown for any 5xx server-side failure. */
+declare class ServerError extends VecminError {
+    constructor(message?: string, code?: number);
+}
+/**
+ * Maps an HTTP status code to the most specific {@link VecminError} subclass.
+ * Falls back to a generic {@link VecminError} for unrecognised codes.
+ */
+declare function createErrorFromStatus(status: number, message: string): VecminError;
+
+export { AuthManager, AuthenticationError, type ClusterStatus, type Collection, type CollectionStats, type CreateCollectionParams, type IndexInfo, type IndexType, type InsertParams, type JsonRpcRequest, type JsonRpcResponse, type LoginParams, type MCPClientOptions, type MCPEventMap, type MCPOptions, type MCPSearchResult, type MetricType, type Node, NotFoundError, PaymentRequiredError, PermissionError, RateLimitError, type RetryOptions, type SearchMemoryParams, type SearchParams, type SearchResult, ServerError, type StoreMemoryParams, VecminClient, type VecminClientOptions, VecminDBVectorStore, VecminError, VecminMCPClient, type VecminResponse, type VecminVectorStoreOptions, type Vector, createErrorFromStatus, fetchJson, resolveRetryOptions, withRetry };