@synapcores/sdk 0.3.0 → 0.4.0

package/dist/index.mjs

@@ -332,6 +332,125 @@ var Collection = class {
   }
 };
 
+// src/vector_collection.ts
+var VectorCollection = class {
+  constructor(client, name) {
+    this.client = client;
+    this.name = name;
+  }
+  get basePath() {
+    return `/vectors/collections/${encodeURIComponent(this.name)}`;
+  }
+  /**
+   * Insert one or more vectors.
+   *
+   * Wire: `POST /v1/vectors/collections/{name}/vectors` with
+   * `{ vectors: [{ id, values, metadata }] }`.
+   *
+   * Accepts either a single record or an array — the SDK always sends
+   * the wrapped `{ vectors: [...] }` envelope the gateway expects.
+   */
+  async insert(records) {
+    const vectors = Array.isArray(records) ? records : [records];
+    const { data } = await this.client._getHttpClient().post(
+      `${this.basePath}/vectors`,
+      { vectors }
+    );
+    return data?.data ?? data;
+  }
+  /**
+   * k-NN search over the vector collection.
+   *
+   * Wire: `POST /v1/vectors/collections/{name}/search` with
+   * `{ vector, k, include_metadata, filter? }`.
+   *
+   * Returns the bare array of hits — gateway envelope (`{data: [...]}`) is
+   * unwrapped automatically for parity with `Collection.vectorSearch`.
+   */
+  async search(options) {
+    const k = options.k ?? options.topK ?? 10;
+    const body = {
+      vector: options.vector,
+      k,
+      include_metadata: options.includeMetadata !== false
+    };
+    if (options.filter !== void 0) body.filter = options.filter;
+    const { data } = await this.client._getHttpClient().post(
+      `${this.basePath}/search`,
+      body
+    );
+    const inner = data?.data ?? data;
+    if (Array.isArray(inner)) return inner;
+    return inner?.matches ?? inner?.results ?? inner?.hits ?? [];
+  }
+  /**
+   * Fetch a single vector by id.
+   *
+   * Wire: `GET /v1/vectors/collections/{name}/vectors/{id}`. Returns the
+   * gateway payload `{ id, values, metadata }` (envelope unwrapped) or
+   * `null` on 404.
+   */
+  async get(id) {
+    try {
+      const { data } = await this.client._getHttpClient().get(
+        `${this.basePath}/vectors/${encodeURIComponent(id)}`
+      );
+      return data?.data ?? data;
+    } catch (err) {
+      if (err?.code === "NOT_FOUND" || err?.status === 404) return null;
+      throw err;
+    }
+  }
+  /**
+   * Delete one or more vectors by id.
+   *
+   * Single-id wire: `DELETE /v1/vectors/collections/{name}/vectors/{id}`.
+   * Bulk wire: `DELETE /v1/vectors/collections/{name}/vectors` with
+   * `{ ids: [...] }` body.
+   */
+  async delete(ids) {
+    if (typeof ids === "string") {
+      const { data: data2 } = await this.client._getHttpClient().delete(
+        `${this.basePath}/vectors/${encodeURIComponent(ids)}`
+      );
+      return data2?.data ?? data2;
+    }
+    const { data } = await this.client._getHttpClient().request({
+      method: "DELETE",
+      url: `${this.basePath}/vectors`,
+      data: { ids }
+    });
+    return data?.data ?? data;
+  }
+  /**
+   * Vector count.
+   *
+   * Wire: `GET /v1/vectors/collections/{name}/count` if the gateway
+   * exposes it, otherwise falls back to `info().vector_count`.
+   */
+  async count() {
+    try {
+      const { data } = await this.client._getHttpClient().get(`${this.basePath}/count`);
+      const inner = data?.data ?? data;
+      const n = typeof inner === "number" ? inner : inner?.count ?? inner?.vector_count;
+      if (typeof n === "number") return n;
+    } catch {
+    }
+    const info = await this.info();
+    return typeof info?.vector_count === "number" ? info.vector_count : 0;
+  }
+  /**
+   * Collection metadata.
+   *
+   * Wire: `GET /v1/vectors/collections/{name}` returning
+   * `{ name, dimensions, vector_count, distance_metric, index_type }`.
+   */
+  async info() {
+    const { data } = await this.client._getHttpClient().get(this.basePath);
+    return data?.data ?? data;
+  }
+};
+
 // src/automl.ts
 var AutoMLModel = class {
   constructor(client, info) {
@@ -2773,6 +2892,20 @@ var SynapCores = class {
     this.collectionsCache = /* @__PURE__ */ new Map();
     this.currentTransaction = null;
     this.preparedStatements = /* @__PURE__ */ new Map();
+    // =================================================================
+    // VECTOR COLLECTIONS — /v1/vectors/collections/{name}
+    //
+    // The gateway exposes two parallel "collection" worlds:
+    //  (a) document-store collections under /v1/collections (above), and
+    //  (b) vector collections under /v1/vectors/collections (below).
+    //
+    // v0.3.0 only wrapped (a) so vector-first users had to drop down to
+    // `_getHttpClient()` to call (b) directly. v0.4.0 adds first-class
+    // helpers — `createVectorCollection`, `vectorCollection(name)`,
+    // `listVectorCollections`, `deleteVectorCollection` — that target (b)
+    // and return a typed `VectorCollection` handle.
+    // =================================================================
+    this.vectorCollectionsCache = /* @__PURE__ */ new Map();
     this.config = {
       host: config.host || "localhost",
       port: config.port || 8080,
@@ -2795,14 +2928,14 @@ var SynapCores = class {
     if (this.config.jwtToken) {
       authHeader["Authorization"] = `Bearer ${this.config.jwtToken}`;
     } else if (this.config.apiKey) {
-      authHeader["X-API-Key"] = this.config.apiKey;
+      authHeader["Authorization"] = `Bearer ${this.config.apiKey}`;
     }
     this.httpClient = axios.create({
       baseURL,
       timeout: this.config.timeout,
       headers: {
         "Content-Type": "application/json",
-        "User-Agent": "synapcores-nodejs/0.3.0",
+        "User-Agent": "synapcores-nodejs/0.4.0",
         ...authHeader
       },
       ...httpsAgent && { httpsAgent }
@@ -3027,6 +3160,67 @@ var SynapCores = class {
     await this.httpClient.delete(`/collections/${name}`);
     this.collectionsCache.delete(name);
   }
+  /**
+   * Create a vector collection.
+   *
+   * Wire: `POST /v1/vectors/collections` with
+   * `{ name, dimensions, distance_metric }`. Distinct from
+   * `createCollection`, which targets the document-store subsystem.
+   *
+   * @example
+   *   const coll = await client.createVectorCollection({
+   *     name: 'memory_v1', dimensions: 1536, distance_metric: 'cosine',
+   *   });
+   *   await coll.insert({ id: 'v1', values: [...], metadata: { ... } });
+   */
+  async createVectorCollection(options) {
+    await this.httpClient.post("/vectors/collections", {
+      name: options.name,
+      dimensions: options.dimensions,
+      distance_metric: options.distance_metric ?? "cosine"
+    });
+    const coll = new VectorCollection(this, options.name);
+    this.vectorCollectionsCache.set(options.name, coll);
+    return coll;
+  }
+  /**
+   * Synchronous accessor for an existing vector collection. Does not
+   * round-trip to the gateway — use `createVectorCollection` if you
+   * need to provision the collection first, or `listVectorCollections`
+   * to confirm existence.
+   *
+   * v0.4.0 split: this targets the **vector subsystem**
+   * (`/v1/vectors/collections/{name}`). `client.collection(name)` still
+   * returns a document-store `Collection` for the legacy subsystem.
+   */
+  vectorCollection(name) {
+    const cached = this.vectorCollectionsCache.get(name);
+    if (cached) return cached;
+    const coll = new VectorCollection(this, name);
+    this.vectorCollectionsCache.set(name, coll);
+    return coll;
+  }
+  /**
+   * List vector collections.
+   *
+   * Wire: `GET /v1/vectors/collections`. Returns the bare array of
+   * collection-info objects (envelope unwrapped).
+   */
+  async listVectorCollections() {
+    const { data } = await this.httpClient.get("/vectors/collections");
+    const inner = data?.data ?? data;
+    if (Array.isArray(inner)) return inner;
+    return inner?.items ?? inner?.collections ?? [];
+  }
+  /**
+   * Delete a vector collection.
+   *
+   * Wire: `DELETE /v1/vectors/collections/{name}`.
+   */
+  async deleteVectorCollection(name) {
+    await this.httpClient.delete(`/vectors/collections/${encodeURIComponent(name)}`);
+    this.vectorCollectionsCache.delete(name);
+  }
   /**
    * Execute SQL query (legacy method for backward compatibility)
    * @deprecated Use executeQuery for new code
@@ -3941,7 +4135,7 @@ var SynapCores = class {
 
 // src/index.ts
 import { z } from "zod";
-var VERSION = "0.3.0";
+var VERSION = "0.4.0";
 export {
   AuthenticationError,
   AutoMLClient,
@@ -3975,6 +4169,7 @@ export {
   Tx,
   VERSION,
   ValidationError,
+  VectorCollection,
   VectorError,
   z
 };