@synapcores/sdk 0.2.1 → 0.4.0

package/dist/index.js

@@ -62,6 +62,7 @@ __export(index_exports, {
   Tx: () => Tx,
   VERSION: () => VERSION,
   ValidationError: () => ValidationError,
+  VectorCollection: () => VectorCollection,
   VectorError: () => VectorError,
   z: () => import_zod.z
 });
@@ -316,20 +317,20 @@ var Collection = class {
   }
   async vectorSearch(options) {
     const { data } = await this.client._getHttpClient().post(
-      `${this.basePath}/vector_search`,
+      `/vectors/collections/${this.name}/search`,
       {
         vector: options.vector,
-        field: options.field || "embedding",
-        top_k: options.topK || 10,
+        k: options.topK || 10,
         filter: options.filter,
-        distance_metric: options.distanceMetric || "cosine",
-        include_metadata: options.includeMetadata
+        include_metadata: options.includeMetadata !== false
       }
     );
+    const inner = data?.data ?? data;
+    const matches = Array.isArray(inner) ? inner : inner?.matches ?? inner?.results ?? inner?.documents ?? data?.matches ?? data?.results ?? data?.documents ?? [];
     return {
-      documents: data.documents,
-      total: data.total,
-      tookMs: data.took_ms
+      documents: matches,
+      total: (inner && !Array.isArray(inner) ? inner.total : void 0) ?? matches.length,
+      tookMs: (inner && !Array.isArray(inner) ? inner.took_ms : void 0) ?? data?.took_ms
     };
   }
   async query(options = {}) {
@@ -394,6 +395,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) {
@@ -467,27 +587,48 @@ var AutoMLClient = class {
     return new AutoMLModel(this, modelInfo);
   }
   async getModel(modelId) {
-    const { data } = await this.synapCores._getHttpClient().get(
-      `/automl/models/${modelId}`
-    );
-    const modelInfo = {
-      id: data.id,
-      name: data.name,
-      task: data.task,
-      status: data.status,
-      accuracy: data.accuracy,
-      createdAt: new Date(data.created_at ?? Date.now()),
-      updatedAt: data.updated_at ? new Date(data.updated_at) : void 0,
-      config: data.config ?? {}
-    };
-    return new AutoMLModel(this, modelInfo);
+    try {
+      const { data } = await this.synapCores._getHttpClient().get(
+        `/automl/models/${modelId}`
+      );
+      const m = data?.data ?? data;
+      const modelInfo = {
+        id: m.id ?? modelId,
+        name: m.name ?? modelId,
+        task: m.task,
+        status: m.status,
+        accuracy: m.accuracy,
+        createdAt: new Date(m.created_at ?? Date.now()),
+        updatedAt: m.updated_at ? new Date(m.updated_at) : void 0,
+        config: m.config ?? {}
+      };
+      return new AutoMLModel(this, modelInfo);
+    } catch (err) {
+      const status = err?.statusCode ?? err?.response?.status;
+      const code = err?.code;
+      if (status === 404 || code === "NOT_FOUND") {
+        const modelInfo = {
+          id: modelId,
+          name: modelId,
+          task: void 0,
+          status: "unknown",
+          accuracy: void 0,
+          createdAt: /* @__PURE__ */ new Date(),
+          updatedAt: void 0,
+          config: {}
+        };
+        return new AutoMLModel(this, modelInfo);
+      }
+      throw err;
+    }
   }
   async listModels(filters) {
     const { data } = await this.synapCores._getHttpClient().get("/automl/models", {
       params: filters
     });
-    return (data.models ?? data ?? []).map((model) => ({
-      id: model.id,
+    const list = Array.isArray(data) ? data : Array.isArray(data?.data) ? data.data : Array.isArray(data?.models) ? data.models : Array.isArray(data?.data?.items) ? data.data.items : [];
+    return list.map((model) => ({
+      id: model.id ?? model.name,
       name: model.name,
       task: model.task,
       status: model.status,
@@ -1998,23 +2139,24 @@ var GraphsApi = class {
   constructor(synapCores) {
     this.synapCores = synapCores;
   }
+  // v0.3.0: gateway routes live under /graph/graphs, not /graphs.
   async list() {
-    const { data } = await this.synapCores._getHttpClient().get("/graphs");
+    const { data } = await this.synapCores._getHttpClient().get("/graph/graphs");
     return (data.graphs ?? data ?? []).map((g) => this.normalize(g));
   }
   async create(name, opts = {}) {
-    const { data } = await this.synapCores._getHttpClient().post("/graphs", {
+    const { data } = await this.synapCores._getHttpClient().post("/graph/graphs", {
       name,
       description: opts.description
     });
     return this.normalize(data);
   }
   async get(name) {
-    const { data } = await this.synapCores._getHttpClient().get(`/graphs/${name}`);
+    const { data } = await this.synapCores._getHttpClient().get(`/graph/graphs/${name}`);
     return this.normalize(data);
   }
   async delete(name) {
-    await this.synapCores._getHttpClient().delete(`/graphs/${name}`);
+    await this.synapCores._getHttpClient().delete(`/graph/graphs/${name}`);
   }
   normalize(data) {
     return {
@@ -2813,6 +2955,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,
@@ -2835,14 +2991,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 = import_axios.default.create({
       baseURL,
       timeout: this.config.timeout,
       headers: {
         "Content-Type": "application/json",
-        "User-Agent": "synapcores-nodejs/0.2.0",
+        "User-Agent": "synapcores-nodejs/0.4.0",
         ...authHeader
       },
       ...httpsAgent && { httpsAgent }
@@ -3008,15 +3164,35 @@ var SynapCores = class {
     this.collectionsCache.set(name, collection);
     return collection;
   }
+  /**
+   * Synchronous accessor that returns a Collection handle without round-tripping
+   * to the gateway. Use this when you already know the collection exists and just
+   * want to issue a vectorSearch / search / insert against it.
+   *
+   * v0.3.0: added so `client.collection(name).vectorSearch(...)` works without
+   * a preceding await on getCollection().
+   */
+  collection(name) {
+    if (this.collectionsCache.has(name)) {
+      return this.collectionsCache.get(name);
+    }
+    const c = new Collection(this, name);
+    this.collectionsCache.set(name, c);
+    return c;
+  }
   /**
    * List collections (legacy method for backward compatibility)
    */
   async listCollections() {
     const result = await this.listCollectionsDetailed();
-    return result.collections.map((c) => c.name);
+    return (result.collections ?? []).map((c) => c.name);
   }
   /**
    * List collections with detailed information matching the database integration guide format
+   *
+   * v0.3.0: gateway returns an envelope { data: { items, total, page, page_size, ... }, meta }.
+   * We normalise that into the SDK's { collections, total, page, pageSize } shape and also
+   * accept legacy { collections: [...] } / bare arrays for forward-compat.
    */
   async listCollectionsDetailed(options) {
     const params = new URLSearchParams();
@@ -3028,7 +3204,14 @@ var SynapCores = class {
     const { data } = await this.httpClient.get(
       `/collections${params.toString() ? `?${params.toString()}` : ""}`
     );
-    return data;
+    const inner = data?.data ?? data;
+    const items = Array.isArray(inner) ? inner : inner?.items ?? inner?.collections ?? [];
+    return {
+      collections: items,
+      total: inner?.total ?? items.length,
+      page: inner?.page ?? 1,
+      pageSize: inner?.page_size ?? inner?.pageSize ?? items.length
+    };
   }
   async getDocuments(collectionName, page, pageSize) {
     const { data } = await this.httpClient.get(
@@ -3040,6 +3223,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
@@ -3954,7 +4198,7 @@ var SynapCores = class {
 
 // src/index.ts
 var import_zod = require("zod");
-var VERSION = "0.2.0";
+var VERSION = "0.4.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthenticationError,
@@ -3989,6 +4233,7 @@ var VERSION = "0.2.0";
   Tx,
   VERSION,
   ValidationError,
+  VectorCollection,
   VectorError,
   z
 });