vecmindb 1.0.0-beta

package/dist/index.js

@@ -0,0 +1,1205 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthManager: () => AuthManager,
+  AuthenticationError: () => AuthenticationError,
+  NotFoundError: () => NotFoundError,
+  PaymentRequiredError: () => PaymentRequiredError,
+  PermissionError: () => PermissionError,
+  RateLimitError: () => RateLimitError,
+  ServerError: () => ServerError,
+  VecminClient: () => VecminClient,
+  VecminDBVectorStore: () => VecminDBVectorStore,
+  VecminError: () => VecminError,
+  VecminMCPClient: () => VecminMCPClient,
+  createErrorFromStatus: () => createErrorFromStatus,
+  fetchJson: () => fetchJson,
+  resolveRetryOptions: () => resolveRetryOptions,
+  withRetry: () => withRetry
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var VecminError = class extends Error {
+  /** HTTP-style status code from the server response. */
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "VecminError";
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthenticationError = class extends VecminError {
+  constructor(message = "Authentication failed or missing credentials") {
+    super(message, 401);
+    this.name = "AuthenticationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var PermissionError = class extends VecminError {
+  constructor(message = "Insufficient permissions") {
+    super(message, 403);
+    this.name = "PermissionError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var PaymentRequiredError = class extends VecminError {
+  constructor(message = "Subscription payment or valid license key required. Please register/activate your license at https://lingxinmind.com") {
+    super(message, 402);
+    this.name = "PaymentRequiredError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var NotFoundError = class extends VecminError {
+  constructor(message = "Resource not found") {
+    super(message, 404);
+    this.name = "NotFoundError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var RateLimitError = class extends VecminError {
+  constructor(message = "Rate limit exceeded") {
+    super(message, 429);
+    this.name = "RateLimitError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ServerError = class extends VecminError {
+  constructor(message = "Internal server error", code = 500) {
+    super(message, code);
+    this.name = "ServerError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+function createErrorFromStatus(status, message) {
+  switch (status) {
+    case 401:
+      return new AuthenticationError(message);
+    case 402:
+      return new PaymentRequiredError(message);
+    case 403:
+      return new PermissionError(message);
+    case 404:
+      return new NotFoundError(message);
+    case 429:
+      return new RateLimitError(message);
+    default:
+      if (status >= 500 && status < 600) {
+        return new ServerError(message, status);
+      }
+      return new VecminError(message, status);
+  }
+}
+
+// src/retry.ts
+var DEFAULTS = {
+  maxRetries: 3,
+  backoffFactor: 0.5,
+  retryableStatusCodes: [429, 500, 502, 503, 504]
+};
+function resolveRetryOptions(opts) {
+  return {
+    maxRetries: opts?.maxRetries ?? DEFAULTS.maxRetries,
+    backoffFactor: opts?.backoffFactor ?? DEFAULTS.backoffFactor,
+    retryableStatusCodes: opts?.retryableStatusCodes ?? DEFAULTS.retryableStatusCodes
+  };
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRetryable(status, retryableCodes) {
+  return retryableCodes.includes(status);
+}
+async function withRetry(fn, options) {
+  const opts = resolveRetryOptions(options);
+  let lastError;
+  for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (err instanceof VecminError && isRetryable(err.code, opts.retryableStatusCodes)) {
+        lastError = err;
+        let delayMs;
+        if (err instanceof RateLimitError && err.retryAfter) {
+          delayMs = (err.retryAfter ?? 1) * 1e3;
+        } else {
+          delayMs = opts.backoffFactor * Math.pow(2, attempt) * 1e3;
+        }
+        const jitter = Math.random() * 200 - 100;
+        await sleep(Math.max(0, delayMs + jitter));
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw lastError ?? new VecminError("All retry attempts exhausted", 0);
+}
+async function fetchJson(url, init, retryOpts) {
+  return withRetry(async () => {
+    const res = await fetch(url, init);
+    const body = await res.json();
+    if (!res.ok) {
+      const message = body?.error ?? body?.message ?? `HTTP ${res.status}`;
+      const code = body?.code ?? res.status;
+      throw createErrorFromStatus(code, message);
+    }
+    return body?.data !== void 0 ? body.data : body;
+  }, retryOpts);
+}
+
+// src/auth.ts
+function decodeJwtPayload(token) {
+  try {
+    const parts = token.split(".");
+    if (parts.length < 2) return null;
+    const base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const json = decodeURIComponent(
+      atob(base64).split("").map((c) => "%" + ("00" + c.charCodeAt(0).toString(16)).slice(-2)).join("")
+    );
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+function isJwtExpiringSoon(token, bufferMs = 5 * 60 * 1e3) {
+  const payload = decodeJwtPayload(token);
+  if (!payload) return true;
+  const exp = payload["exp"];
+  if (typeof exp !== "number") return true;
+  return Date.now() >= exp * 1e3 - bufferMs;
+}
+var AuthManager = class {
+  apiKey;
+  jwt;
+  loginParams;
+  baseUrl;
+  refreshPromise = null;
+  constructor(baseUrl, options) {
+    this.baseUrl = baseUrl;
+    this.apiKey = options.apiKey;
+    this.jwt = options.jwt;
+  }
+  /**
+   * Store login credentials so the manager can automatically refresh the JWT.
+   * Called internally by {@link VecminClient.login}.
+   */
+  setLoginCredentials(params, jwt) {
+    this.loginParams = params;
+    this.jwt = jwt;
+  }
+  /**
+   * 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.
+   */
+  async getHeaders() {
+    const headers = {};
+    if (this.jwt) {
+      if (isJwtExpiringSoon(this.jwt)) {
+        const freshJwt = await this.refreshJwt();
+        if (freshJwt) {
+          headers["Authorization"] = `Bearer ${freshJwt}`;
+        } else if (this.apiKey) {
+          headers["x-api-key"] = this.apiKey;
+        }
+      } else {
+        headers["Authorization"] = `Bearer ${this.jwt}`;
+      }
+    } else if (this.apiKey) {
+      headers["x-api-key"] = this.apiKey;
+    }
+    return headers;
+  }
+  /**
+   * Attempt to refresh the JWT by re-posting the stored login credentials.
+   * Uses a singleton promise so concurrent calls don't trigger multiple logins.
+   */
+  async refreshJwt() {
+    if (!this.loginParams) return null;
+    if (this.refreshPromise) return this.refreshPromise;
+    this.refreshPromise = (async () => {
+      try {
+        const result = await fetchJson(
+          `${this.baseUrl}/api/v1/cluster/login`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(this.loginParams)
+          },
+          { maxRetries: 1 }
+          // Don't retry aggressively on auth failures.
+        );
+        this.jwt = result;
+        return result;
+      } catch {
+        return null;
+      } finally {
+        this.refreshPromise = null;
+      }
+    })();
+    return this.refreshPromise;
+  }
+};
+
+// src/client.ts
+var VecminClient = class {
+  /** Resolved base URL (trailing slash stripped). */
+  baseUrl;
+  /** API path prefix. */
+  apiUrl;
+  /** MCP path prefix. */
+  mcpUrl;
+  /** Authentication manager. */
+  auth;
+  /** Request timeout in milliseconds. */
+  timeout;
+  /** Retry configuration propagated to every request. */
+  retryOptions;
+  /** Default headers merged into every request. */
+  defaultHeaders;
+  /** Abort controllers for in-flight requests (used by `close()`). */
+  controllers = /* @__PURE__ */ new Set();
+  /** Whether the client has been closed. */
+  closed = false;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.apiUrl = `${this.baseUrl}/api/v1`;
+    this.mcpUrl = `${this.baseUrl}/mcp`;
+    this.auth = new AuthManager(this.baseUrl, options);
+    this.timeout = options.timeout ?? 3e4;
+    this.retryOptions = {
+      maxRetries: options.maxRetries ?? 3,
+      backoffFactor: options.backoffFactor ?? 0.5
+    };
+    this.defaultHeaders = {
+      "Content-Type": "application/json",
+      ...options.defaultHeaders
+    };
+    if (options.agentId) this.defaultHeaders["x-agent-id"] = options.agentId;
+    if (options.modelId) this.defaultHeaders["x-model-id"] = options.modelId;
+  }
+  // -----------------------------------------------------------------------
+  // Internal helpers
+  // -----------------------------------------------------------------------
+  /** Build the full headers map for an outgoing request. */
+  async buildHeaders() {
+    const authHeaders = await this.auth.getHeaders();
+    return { ...this.defaultHeaders, ...authHeaders };
+  }
+  /** Create an AbortController with the configured timeout and track it. */
+  createController() {
+    const controller = new AbortController();
+    this.controllers.add(controller);
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    if (timer.unref) timer.unref();
+    controller.signal.addEventListener("abort", () => {
+      this.controllers.delete(controller);
+    });
+    return controller;
+  }
+  /** Perform a JSON GET request. */
+  async get(path) {
+    this.assertOpen();
+    const controller = this.createController();
+    try {
+      return await fetchJson(
+        `${this.apiUrl}${path}`,
+        {
+          method: "GET",
+          headers: await this.buildHeaders(),
+          signal: controller.signal
+        },
+        this.retryOptions
+      );
+    } finally {
+      this.controllers.delete(controller);
+    }
+  }
+  /** Perform a JSON POST request. */
+  async post(path, body) {
+    this.assertOpen();
+    const controller = this.createController();
+    try {
+      return await fetchJson(
+        `${this.apiUrl}${path}`,
+        {
+          method: "POST",
+          headers: await this.buildHeaders(),
+          body: body !== void 0 ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        },
+        this.retryOptions
+      );
+    } finally {
+      this.controllers.delete(controller);
+    }
+  }
+  /** Perform a JSON DELETE request. */
+  async del(path) {
+    this.assertOpen();
+    const controller = this.createController();
+    try {
+      return await fetchJson(
+        `${this.apiUrl}${path}`,
+        {
+          method: "DELETE",
+          headers: await this.buildHeaders(),
+          signal: controller.signal
+        },
+        this.retryOptions
+      );
+    } finally {
+      this.controllers.delete(controller);
+    }
+  }
+  /** Throw if the client has been closed. */
+  assertOpen() {
+    if (this.closed) {
+      throw new Error("VecminClient has been closed");
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Collection Management
+  // -----------------------------------------------------------------------
+  /**
+   * Create a new collection.
+   *
+   * @example
+   * ```ts
+   * const col = await client.createCollection({
+   *   name: "docs",
+   *   dimension: 1536,
+   *   metric_type: "Cosine",
+   *   index_type: "HNSW",
+   * });
+   * ```
+   */
+  async createCollection(params) {
+    return this.post("/collections", params);
+  }
+  /**
+   * List all collections.
+   *
+   * @example
+   * ```ts
+   * const collections = await client.listCollections();
+   * ```
+   */
+  async listCollections() {
+    return this.get("/collections");
+  }
+  /**
+   * Get details for a specific collection.
+   *
+   * @example
+   * ```ts
+   * const col = await client.getCollection("docs");
+   * ```
+   */
+  async getCollection(name) {
+    return this.get(`/collections/${encodeURIComponent(name)}`);
+  }
+  /**
+   * Delete a collection and all its data.
+   *
+   * @example
+   * ```ts
+   * await client.deleteCollection("docs");
+   * ```
+   */
+  async deleteCollection(name) {
+    await this.del(`/collections/${encodeURIComponent(name)}`);
+  }
+  /**
+   * Get statistics for a collection.
+   *
+   * @example
+   * ```ts
+   * const stats = await client.getCollectionStats("docs");
+   * console.log(`Vectors: ${stats.vector_count}`);
+   * ```
+   */
+  async getCollectionStats(name) {
+    return this.get(`/collections/${encodeURIComponent(name)}/stats`);
+  }
+  // -----------------------------------------------------------------------
+  // Vector Operations
+  // -----------------------------------------------------------------------
+  /**
+   * 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" },
+   * });
+   * ```
+   */
+  async insert(collection, params) {
+    return this.post(`/collections/${encodeURIComponent(collection)}/insert`, params);
+  }
+  /**
+   * 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" } },
+   * ]);
+   * ```
+   */
+  async batchInsert(collection, vectors) {
+    return this.post(`/collections/${encodeURIComponent(collection)}/batch`, vectors);
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async search(collection, params) {
+    return this.post(`/collections/${encodeURIComponent(collection)}/search`, params);
+  }
+  /**
+   * Retrieve a single vector by its ID.
+   *
+   * @example
+   * ```ts
+   * const vec = await client.getVector("docs", "abc-123");
+   * ```
+   */
+  async getVector(collection, id) {
+    return this.get(`/collections/${encodeURIComponent(collection)}/vectors/${encodeURIComponent(id)}`);
+  }
+  /**
+   * Delete a single vector by its ID.
+   *
+   * @example
+   * ```ts
+   * await client.deleteVector("docs", "abc-123");
+   * ```
+   */
+  async deleteVector(collection, id) {
+    await this.del(`/collections/${encodeURIComponent(collection)}/vectors/${encodeURIComponent(id)}`);
+  }
+  // -----------------------------------------------------------------------
+  // Index Management
+  // -----------------------------------------------------------------------
+  /**
+   * Trigger an index rebuild for a collection.
+   *
+   * @example
+   * ```ts
+   * await client.rebuildIndex("docs");
+   * ```
+   */
+  async rebuildIndex(collection) {
+    await this.post(`/collections/${encodeURIComponent(collection)}/rebuild_index`);
+  }
+  /**
+   * List all indexes in the cluster.
+   *
+   * @example
+   * ```ts
+   * const indexes = await client.listIndexes();
+   * ```
+   */
+  async listIndexes() {
+    return this.get("/indexes");
+  }
+  /**
+   * Rebuild a named index.
+   *
+   * @example
+   * ```ts
+   * await client.rebuildNamedIndex("docs_hnsw");
+   * ```
+   */
+  async rebuildNamedIndex(name) {
+    await this.post(`/indexes/${encodeURIComponent(name)}/rebuild`);
+  }
+  /**
+   * Optimize a named index.
+   *
+   * @example
+   * ```ts
+   * await client.optimizeIndex("docs_hnsw");
+   * ```
+   */
+  async optimizeIndex(name) {
+    await this.post(`/indexes/${encodeURIComponent(name)}/optimize`);
+  }
+  // -----------------------------------------------------------------------
+  // Cluster Management
+  // -----------------------------------------------------------------------
+  /**
+   * 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" });
+   * ```
+   */
+  async login(credentials) {
+    const jwt = await this.post("/cluster/login", credentials);
+    this.auth.setLoginCredentials(credentials, jwt);
+    return jwt;
+  }
+  /**
+   * List all nodes in the cluster.
+   *
+   * @example
+   * ```ts
+   * const nodes = await client.listNodes();
+   * ```
+   */
+  async listNodes() {
+    return this.get("/cluster/nodes");
+  }
+  /**
+   * Get the overall cluster status.
+   *
+   * @example
+   * ```ts
+   * const status = await client.clusterStatus();
+   * console.log(status.status, status.leader_id);
+   * ```
+   */
+  async clusterStatus() {
+    return this.get("/cluster/status");
+  }
+  /**
+   * Create a cluster snapshot.
+   *
+   * @example
+   * ```ts
+   * await client.createSnapshot();
+   * ```
+   */
+  async createSnapshot() {
+    await this.post("/cluster/snapshot");
+  }
+  // -----------------------------------------------------------------------
+  // MCP Convenience Methods
+  // -----------------------------------------------------------------------
+  /**
+   * 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");
+   * ```
+   */
+  async mcpStoreMemory(text, agentId, options) {
+    const controller = this.createController();
+    try {
+      await fetchJson(
+        `${this.mcpUrl}/messages`,
+        {
+          method: "POST",
+          headers: await this.buildHeaders(),
+          body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: Date.now(),
+            method: "tools/call",
+            params: {
+              name: "store_memory",
+              arguments: {
+                agent_id: agentId,
+                content: text,
+                source: options?.source ?? "typescript-sdk",
+                collection: options?.collection ?? "agent_memory_mcp"
+              }
+            }
+          }),
+          signal: controller.signal
+        },
+        this.retryOptions
+      );
+    } finally {
+      this.controllers.delete(controller);
+    }
+  }
+  /**
+   * Search memories via the MCP `search_memory` tool.
+   *
+   * @example
+   * ```ts
+   * const results = await client.mcpSearchMemory("user preferences", "agent-1", 5);
+   * ```
+   */
+  async mcpSearchMemory(query, agentId, topK = 5) {
+    const controller = this.createController();
+    try {
+      const result = await fetchJson(
+        `${this.mcpUrl}/messages`,
+        {
+          method: "POST",
+          headers: await this.buildHeaders(),
+          body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: Date.now(),
+            method: "tools/call",
+            params: {
+              name: "search_memory",
+              arguments: {
+                agent_id: agentId,
+                query,
+                top_k: topK
+              }
+            }
+          }),
+          signal: controller.signal
+        },
+        this.retryOptions
+      );
+      return result;
+    } finally {
+      this.controllers.delete(controller);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Lifecycle
+  // -----------------------------------------------------------------------
+  /**
+   * Gracefully shut down the client.
+   * Aborts all in-flight requests and releases resources.
+   *
+   * @example
+   * ```ts
+   * await client.close();
+   * ```
+   */
+  async close() {
+    this.closed = true;
+    for (const controller of this.controllers) {
+      controller.abort();
+    }
+    this.controllers.clear();
+  }
+};
+
+// src/mcp.ts
+var VecminMCPClient = class {
+  baseUrl;
+  mcpUrl;
+  options;
+  handlers = /* @__PURE__ */ new Map();
+  rpcId = 0;
+  pendingRpc = /* @__PURE__ */ new Map();
+  abortController = null;
+  reader = null;
+  connected = false;
+  constructor(baseUrl, options) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.mcpUrl = `${this.baseUrl}/mcp`;
+    this.options = options ?? {};
+  }
+  // -----------------------------------------------------------------------
+  // Event emitter
+  // -----------------------------------------------------------------------
+  /**
+   * Register an event handler.
+   *
+   * @param event   - One of the {@link MCPEventMap} keys.
+   * @param handler - Callback invoked when the event fires.
+   */
+  on(event, handler) {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this.handlers.get(event).add(handler);
+  }
+  /**
+   * Remove a previously registered event handler.
+   */
+  off(event, handler) {
+    this.handlers.get(event)?.delete(handler);
+  }
+  emit(event, data) {
+    for (const handler of this.handlers.get(event) ?? []) {
+      try {
+        handler(data);
+      } catch {
+      }
+    }
+  }
+  // -----------------------------------------------------------------------
+  // SSE Connection
+  // -----------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async connect() {
+    if (this.connected) return;
+    this.abortController = new AbortController();
+    const headers = {
+      Accept: "text/event-stream"
+    };
+    if (this.options.apiKey) headers["x-api-key"] = this.options.apiKey;
+    if (this.options.jwt) headers["Authorization"] = `Bearer ${this.options.jwt}`;
+    if (this.options.agentId) headers["x-agent-id"] = this.options.agentId;
+    if (this.options.modelId) headers["x-model-id"] = this.options.modelId;
+    const response = await fetch(`${this.mcpUrl}/sse`, {
+      method: "GET",
+      headers,
+      signal: this.abortController.signal
+    });
+    if (!response.ok) {
+      throw createErrorFromStatus(
+        response.status,
+        `SSE connection failed: HTTP ${response.status}`
+      );
+    }
+    const body = response.body;
+    if (!body) {
+      throw new VecminError("SSE connection returned no body", 0);
+    }
+    this.connected = true;
+    this.emit("connected", void 0);
+    this.readSSEStream(body).catch((err) => {
+      if (this.connected) {
+        this.emit("error", err instanceof Error ? err : new Error(String(err)));
+      }
+    });
+  }
+  /**
+   * Read and parse an SSE stream using `eventsource-parser`.
+   */
+  async readSSEStream(stream) {
+    const { createParser } = await import("eventsource-parser");
+    const parser = createParser((event) => {
+      if (!("data" in event)) return;
+      this.emit("event", { event: event.event ?? "message", data: event.data });
+      if (event.data) {
+        try {
+          const json = JSON.parse(event.data);
+          if (json.id !== void 0 && json.id !== null) {
+            const pending = this.pendingRpc.get(json.id);
+            if (pending) {
+              this.pendingRpc.delete(json.id);
+              if (json.error) {
+                pending.reject(
+                  new VecminError(json.error.message ?? "JSON-RPC error", json.error.code)
+                );
+              } else {
+                pending.resolve(json.result);
+              }
+              this.emit("result", { id: json.id, result: json.result });
+            }
+          }
+        } catch {
+        }
+      }
+    });
+    this.reader = stream.getReader();
+    const decoder = new TextDecoder();
+    try {
+      while (true) {
+        const { done, value } = await this.reader.read();
+        if (done) break;
+        parser.feed(decoder.decode(value, { stream: true }));
+      }
+    } finally {
+      this.connected = false;
+      this.emit("disconnected", void 0);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // JSON-RPC Calls
+  // -----------------------------------------------------------------------
+  /**
+   * Send a JSON-RPC 2.0 request to `POST /mcp/messages`.
+   *
+   * @returns The `result` field of the JSON-RPC response.
+   */
+  async rpc(method, params) {
+    const id = ++this.rpcId;
+    const request = {
+      jsonrpc: "2.0",
+      id,
+      method,
+      params
+    };
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.options.apiKey) headers["x-api-key"] = this.options.apiKey;
+    if (this.options.jwt) headers["Authorization"] = `Bearer ${this.options.jwt}`;
+    if (this.options.agentId) headers["x-agent-id"] = this.options.agentId;
+    if (this.options.modelId) headers["x-model-id"] = this.options.modelId;
+    const rpcPromise = new Promise((resolve, reject) => {
+      this.pendingRpc.set(id, { resolve, reject });
+    });
+    const res = await fetch(`${this.mcpUrl}/messages`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(request)
+    });
+    if (!res.ok) {
+      this.pendingRpc.delete(id);
+      throw createErrorFromStatus(res.status, `MCP RPC call failed: HTTP ${res.status}`);
+    }
+    const text = await res.text();
+    if (text) {
+      try {
+        const json = JSON.parse(text);
+        this.pendingRpc.delete(id);
+        if (json.error) {
+          throw new VecminError(json.error.message ?? "JSON-RPC error", json.error.code);
+        }
+        return json.result ?? json;
+      } catch (err) {
+        if (err instanceof VecminError) throw err;
+      }
+    }
+    return rpcPromise;
+  }
+  // -----------------------------------------------------------------------
+  // MCP Tool Methods
+  // -----------------------------------------------------------------------
+  /**
+   * Call the `store_memory` MCP tool.
+   *
+   * @example
+   * ```ts
+   * await mcp.storeMemory({ text: "User prefers dark mode", agent_id: "agent-1" });
+   * ```
+   */
+  async storeMemory(params) {
+    await this.rpc("tools/call", {
+      name: "store_memory",
+      arguments: {
+        agent_id: params.agent_id,
+        text: params.text,
+        source: params.source ?? "typescript-sdk",
+        collection: params.collection ?? "agent_memory_mcp"
+      }
+    });
+  }
+  /**
+   * Call the `search_memory` MCP tool.
+   *
+   * @example
+   * ```ts
+   * const results = await mcp.searchMemory({ query: "preferences", agent_id: "agent-1", top_k: 5 });
+   * ```
+   */
+  async searchMemory(params) {
+    const result = await this.rpc("tools/call", {
+      name: "search_memory",
+      arguments: {
+        agent_id: params.agent_id,
+        query: params.query,
+        top_k: params.top_k ?? 5,
+        collection: params.collection ?? "agent_memory_mcp"
+      }
+    });
+    return result;
+  }
+  // -----------------------------------------------------------------------
+  // Lifecycle
+  // -----------------------------------------------------------------------
+  /**
+   * Close the SSE connection and release all resources.
+   */
+  async disconnect() {
+    this.connected = false;
+    this.abortController?.abort();
+    this.abortController = null;
+    try {
+      await this.reader?.cancel();
+    } catch {
+    }
+    this.reader = null;
+    for (const [id, { reject }] of this.pendingRpc) {
+      reject(new VecminError("MCP client disconnected", 0));
+      this.pendingRpc.delete(id);
+    }
+  }
+};
+
+// src/langchain.ts
+var LangChain = null;
+var LangChainDocs = null;
+async function ensureLangChain() {
+  if (LangChain && LangChainDocs) {
+    return {
+      VectorStore: LangChain.VectorStore,
+      Document: LangChainDocs.Document,
+      Embeddings: (await import("@langchain/core/embeddings")).Embeddings
+    };
+  }
+  try {
+    const vc = await import("@langchain/core/vectorstores");
+    const docs = await import("@langchain/core/documents");
+    const emb = await import("@langchain/core/embeddings");
+    LangChain = vc;
+    LangChainDocs = docs;
+    return {
+      VectorStore: vc.VectorStore,
+      Document: docs.Document,
+      Embeddings: emb.Embeddings
+    };
+  } catch {
+    throw new Error(
+      "@langchain/core is required for VecminDBVectorStore. Install it with: npm install @langchain/core"
+    );
+  }
+}
+var VecminDBVectorStore = class _VecminDBVectorStore {
+  /** Underlying VecminDB client used for all I/O. */
+  client;
+  /** LangChain embeddings instance. */
+  _embeddings;
+  // typed as unknown to avoid requiring @langchain/core at import time
+  /** Collection name in VecminDB. */
+  collectionName;
+  /** Vector dimensionality. */
+  dimension;
+  /** Whether the collection has been ensured to exist. */
+  ensured = false;
+  // LangChain VectorStore interface fields
+  /** @internal */
+  lc_namespace = ["vecmindb", "vectorstores"];
+  /** @internal */
+  lc_serializable = true;
+  constructor(embeddings, options) {
+    this._embeddings = embeddings;
+    this.collectionName = options.collectionName ?? "langchain_memory";
+    this.dimension = options.dimension ?? 1536;
+    this.client = new VecminClient({
+      baseUrl: options.baseUrl,
+      apiKey: options.apiKey,
+      timeout: options.timeout
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Collection bootstrap
+  // -----------------------------------------------------------------------
+  /**
+   * Ensure the target collection exists in VecminDB.
+   * Called lazily before the first write operation.
+   */
+  async ensureCollection() {
+    if (this.ensured) return;
+    try {
+      await this.client.createCollection({
+        name: this.collectionName,
+        dimension: this.dimension,
+        metric_type: "Cosine",
+        index_type: "HNSW",
+        index_params: { m: 16, ef_construction: 100 }
+      });
+    } catch (err) {
+      if (err instanceof Error && err.message?.includes("already exists")) {
+      } else if (err instanceof Error && (err.message?.includes("409") || err.message?.includes("Conflict"))) {
+      } else if (err instanceof Error && err.message?.includes("404") === false) {
+        throw err;
+      }
+    }
+    this.ensured = true;
+  }
+  // -----------------------------------------------------------------------
+  // LangChain VectorStore interface
+  // -----------------------------------------------------------------------
+  /**
+   * Add documents to the vector store.
+   * Embeds the document texts and inserts them into VecminDB.
+   */
+  async addDocuments(documents) {
+    const { Embeddings } = await ensureLangChain();
+    const emb = this._embeddings;
+    const texts = documents.map((d) => d.pageContent);
+    const metadatas = documents.map((d) => d.metadata ?? {});
+    const vectors = await emb.embedDocuments(texts);
+    return this.addVectors(vectors, documents, metadatas);
+  }
+  /**
+   * Add pre-computed vectors to the vector store.
+   */
+  async addVectors(vectors, documents, metadatas) {
+    await this.ensureCollection();
+    const ids = [];
+    for (let i = 0; i < vectors.length; i++) {
+      const doc = documents[i];
+      const meta = {
+        ...metadatas?.[i] ?? doc.metadata ?? {},
+        text: doc.pageContent
+        // Store the text in metadata for retrieval.
+      };
+      const id = await this.client.insert(this.collectionName, {
+        vector: vectors[i],
+        metadata: meta
+      });
+      ids.push(id);
+    }
+    return ids;
+  }
+  /**
+   * Search for the most similar vectors and return results with scores.
+   *
+   * @param query - Query vector.
+   * @param k     - Number of results. @default 4
+   */
+  async similaritySearchVectorWithScore(query, k = 4) {
+    const results = await this.client.search(this.collectionName, {
+      query,
+      k
+    });
+    return results.map((r) => {
+      const meta = r.metadata ?? {};
+      const text = typeof meta["text"] === "string" ? meta["text"] : "";
+      const cleanMeta = { ...meta };
+      delete cleanMeta["text"];
+      return [
+        { pageContent: text, metadata: cleanMeta },
+        r.score
+      ];
+    });
+  }
+  /**
+   * Convenience method: search for similar documents (without scores).
+   */
+  async similaritySearch(query, k = 4) {
+    const { Embeddings } = await ensureLangChain();
+    const emb = this._embeddings;
+    const queryVector = await emb.embedQuery(query);
+    const results = await this.similaritySearchVectorWithScore(queryVector, k);
+    return results.map(([doc]) => doc);
+  }
+  /**
+   * Convenience method: search for similar documents with scores.
+   */
+  async similaritySearchWithScore(query, k = 4) {
+    const { Embeddings } = await ensureLangChain();
+    const emb = this._embeddings;
+    const queryVector = await emb.embedQuery(query);
+    return this.similaritySearchVectorWithScore(queryVector, k);
+  }
+  // -----------------------------------------------------------------------
+  // Static factory methods
+  // -----------------------------------------------------------------------
+  /**
+   * 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 async fromDocuments(documents, embeddings, options) {
+    const store = new _VecminDBVectorStore(embeddings, options);
+    await store.addDocuments(documents);
+    return store;
+  }
+  /**
+   * 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 async fromTexts(texts, metadatas, embeddings, options) {
+    const documents = texts.map((text, i) => ({
+      pageContent: text,
+      metadata: metadatas[i] ?? {}
+    }));
+    return _VecminDBVectorStore.fromDocuments(documents, embeddings, options);
+  }
+  // -----------------------------------------------------------------------
+  // Cleanup
+  // -----------------------------------------------------------------------
+  /**
+   * Close the underlying client connection.
+   */
+  async close() {
+    await this.client.close();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthManager,
+  AuthenticationError,
+  NotFoundError,
+  PaymentRequiredError,
+  PermissionError,
+  RateLimitError,
+  ServerError,
+  VecminClient,
+  VecminDBVectorStore,
+  VecminError,
+  VecminMCPClient,
+  createErrorFromStatus,
+  fetchJson,
+  resolveRetryOptions,
+  withRetry
+});