@wiscale/velesdb-sdk 1.17.0 → 1.18.0

package/dist/index.js

@@ -1815,16 +1815,13 @@ async function getEdgeCount(transport, collection) {
   return response.data?.count ?? 0;
 }
 async function listNodes(transport, collection) {
-  const response = await transport.requestJson(
-    "GET",
-    `${collectionPath(collection)}/graph/nodes`
-  );
+  const response = await transport.requestJson("GET", `${collectionPath(collection)}/graph/nodes`);
   throwOnError(response, `Collection '${collection}'`);
   const data = response.data;
   return { nodeIds: data.node_ids, count: data.count };
 }
-function idToNumber(id) {
-  return typeof id === "string" ? Number(id) : id;
+function idToGraphId(id) {
+  return id;
 }
 async function getNodeEdges(transport, collection, nodeId, options) {
   const params = new URLSearchParams();
@@ -1835,9 +1832,9 @@ async function getNodeEdges(transport, collection, nodeId, options) {
   const response = await transport.requestJson("GET", url);
   throwOnError(response, `Collection '${collection}'`);
   return (response.data?.edges ?? []).map((e) => ({
-    id: idToNumber(e.id),
-    source: idToNumber(e.source),
-    target: idToNumber(e.target),
+    id: e.id,
+    source: e.source,
+    target: e.target,
     label: e.label,
     properties: e.properties
   }));
@@ -1847,7 +1844,7 @@ async function getNodePayload(transport, collection, nodeId) {
   throwOnError(response, `Collection '${collection}'`);
   const data = response.data;
   return {
-    nodeId: idToNumber(data.node_id),
+    nodeId: idToGraphId(data.node_id),
     payload: data.payload
   };
 }
@@ -1871,7 +1868,7 @@ async function graphSearch(transport, collection, request2) {
   throwOnError(response, `Collection '${collection}'`);
   const items = (response.data?.results ?? []).map(
     (r) => ({
-      id: idToNumber(r.id),
+      id: idToGraphId(r.id),
       score: r.score,
       payload: r.payload
     })
@@ -1905,9 +1902,11 @@ async function storeSemanticFact(transport, collection, entry) {
         id: entry.id,
         vector: entry.embedding,
         payload: {
+          // Caller metadata is spread first so the reserved keys below
+          // (`_memory_type`, `text`) always win and cannot be clobbered.
+          ...entry.metadata,
           _memory_type: "semantic",
-          text: entry.text,
-          ...entry.metadata
+          text: entry.text
         }
       }]
     }
@@ -1927,16 +1926,20 @@ async function recordEpisodicEvent(transport, collection, event) {
         id,
         vector: event.embedding,
         payload: {
+          // Caller-supplied data/metadata is spread first so the reserved
+          // keys below (`_memory_type`, `event_type`, `timestamp`) always
+          // win and cannot be clobbered.
+          ...event.data,
+          ...event.metadata,
           _memory_type: "episodic",
           event_type: event.eventType,
-          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-          ...event.data,
-          ...event.metadata
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
         }
       }]
     }
   );
   throwOnError(response);
+  return id;
 }
 async function recallEpisodicEvents(transport, collection, embedding, k = 5) {
   return transport.searchVectors(collection, embedding, k, { _memory_type: "episodic" });
@@ -1949,16 +1952,21 @@ async function storeProceduralPattern(transport, collection, pattern) {
     {
       points: [{
         id,
+        vector: pattern.embedding,
         payload: {
+          // Caller metadata is spread first so the reserved keys below
+          // (`_memory_type`, `name`, `steps`) always win and cannot be
+          // clobbered.
+          ...pattern.metadata,
           _memory_type: "procedural",
           name: pattern.name,
-          steps: pattern.steps,
-          ...pattern.metadata
+          steps: pattern.steps
         }
       }]
     }
   );
   throwOnError(response);
+  return id;
 }
 async function matchProceduralPatterns(transport, collection, embedding, k = 5) {
   return transport.searchVectors(collection, embedding, k, { _memory_type: "procedural" });
@@ -2112,15 +2120,29 @@ async function addEdge(transport, collection, edge) {
   throwOnError(response, `Collection '${collection}'`);
 }
 function toGraphEdge(e) {
-  const toNum = (v) => typeof v === "string" ? Number(v) : v;
   return {
-    id: toNum(e.id),
-    source: toNum(e.source),
-    target: toNum(e.target),
+    id: e.id,
+    source: e.source,
+    target: e.target,
     label: e.label,
     properties: e.properties
   };
 }
+function toTraverseResponse(data) {
+  return {
+    results: data.results.map((r) => ({
+      targetId: r.target_id,
+      depth: r.depth,
+      path: r.path
+    })),
+    nextCursor: data.next_cursor ?? void 0,
+    hasMore: data.has_more,
+    stats: {
+      visited: data.stats.visited,
+      depthReached: data.stats.depth_reached
+    }
+  };
+}
 async function getEdges(transport, collection, options) {
   const queryParams = options?.label ? `?label=${encodeURIComponent(options.label)}` : "";
   const response = await transport.requestJson(
@@ -2144,20 +2166,7 @@ async function traverseGraph(transport, collection, request2) {
     }
   );
   throwOnError(response, `Collection '${collection}'`);
-  const data = response.data;
-  return {
-    results: data.results.map((r) => ({
-      targetId: r.target_id,
-      depth: r.depth,
-      path: r.path
-    })),
-    nextCursor: data.next_cursor ?? void 0,
-    hasMore: data.has_more,
-    stats: {
-      visited: data.stats.visited,
-      depthReached: data.stats.depth_reached
-    }
-  };
+  return toTraverseResponse(response.data);
 }
 async function getNodeDegree(transport, collection, nodeId) {
   const response = await transport.requestJson(
@@ -2192,20 +2201,7 @@ async function traverseParallel(transport, collection, request2) {
     }
   );
   throwOnError(response, `Collection '${collection}'`);
-  const data = response.data;
-  return {
-    results: data.results.map((r) => ({
-      targetId: r.target_id,
-      depth: r.depth,
-      path: r.path
-    })),
-    nextCursor: data.next_cursor ?? void 0,
-    hasMore: data.has_more,
-    stats: {
-      visited: data.stats.visited,
-      depthReached: data.stats.depth_reached
-    }
-  };
+  return toTraverseResponse(response.data);
 }
 
 // src/backends/query-backend.ts
@@ -2890,7 +2886,16 @@ var AgentMemoryClient = class {
     this.backend = backend;
     this.config = config;
   }
-  /** Configured embedding dimension (default: 384) */
+  /**
+   * Advisory embedding dimension passed at construction (default: 384).
+   *
+   * This value is **not** enforced and does not create or size any
+   * collection — the dimension that actually governs storage and search
+   * is the one fixed when the collection was created
+   * (`db.createCollection(name, { dimension, metric: 'cosine' })`).
+   * Embeddings you pass to `storeFact` / `recordEvent` / `learnProcedure`
+   * must match that collection dimension.
+   */
   get dimension() {
     return this.config?.dimension ?? 384;
   }
@@ -2902,7 +2907,7 @@ var AgentMemoryClient = class {
   async searchFacts(collection, embedding, k = 5) {
     return this.backend.searchSemanticMemory(collection, embedding, k);
   }
-  /** Record an episodic event */
+  /** Record an episodic event. Returns the generated point ID. */
   async recordEvent(collection, event) {
     return this.backend.recordEpisodicEvent(collection, event);
   }
@@ -2910,7 +2915,7 @@ var AgentMemoryClient = class {
   async recallEvents(collection, embedding, k = 5) {
     return this.backend.recallEpisodicEvents(collection, embedding, k);
   }
-  /** Store a procedural pattern */
+  /** Store a procedural pattern. Returns the generated point ID. */
   async learnProcedure(collection, pattern) {
     return this.backend.storeProceduralPattern(collection, pattern);
   }
@@ -2918,6 +2923,10 @@ var AgentMemoryClient = class {
   async recallProcedures(collection, embedding, k = 5) {
     return this.backend.matchProceduralPatterns(collection, embedding, k);
   }
+  /** Delete a memory entry (fact, event, or procedure) by its point ID. */
+  async deleteMemory(collection, id) {
+    return this.backend.delete(collection, id);
+  }
 };
 
 // src/client/validation.ts
@@ -3057,12 +3066,15 @@ function aggregate2(backend, queryString, params, options) {
 }
 
 // src/client/graph-methods.ts
+function isGraphNodeId(value) {
+  return typeof value === "number" || typeof value === "string";
+}
 function addEdge2(backend, collection, edge) {
   if (!edge.label || typeof edge.label !== "string") {
     throw new ValidationError("Edge label is required and must be a string");
   }
-  if (typeof edge.source !== "number" || typeof edge.target !== "number") {
-    throw new ValidationError("Edge source and target must be numbers");
+  if (!isGraphNodeId(edge.source) || !isGraphNodeId(edge.target)) {
+    throw new ValidationError("Edge source and target must be numbers or strings");
   }
   return backend.addEdge(collection, edge);
 }
@@ -3070,8 +3082,8 @@ function getEdges2(backend, collection, options) {
   return backend.getEdges(collection, options);
 }
 function traverseGraph2(backend, collection, request2) {
-  if (typeof request2.source !== "number") {
-    throw new ValidationError("Source node ID must be a number");
+  if (!isGraphNodeId(request2.source)) {
+    throw new ValidationError("Source node ID must be a number or string");
   }
   if (request2.strategy && !["bfs", "dfs"].includes(request2.strategy)) {
     throw new ValidationError("Strategy must be 'bfs' or 'dfs'");
@@ -3082,6 +3094,9 @@ function traverseParallel2(backend, collection, request2) {
   if (!Array.isArray(request2.sources) || request2.sources.length === 0) {
     throw new ValidationError("At least one source node ID is required");
   }
+  if (!request2.sources.every(isGraphNodeId)) {
+    throw new ValidationError("Source node IDs must be numbers or strings");
+  }
   return backend.traverseParallel(collection, request2);
 }
 function getNodeDegree2(backend, collection, nodeId) {

package/dist/index.mjs

@@ -1676,16 +1676,13 @@ async function getEdgeCount(transport, collection) {
   return response.data?.count ?? 0;
 }
 async function listNodes(transport, collection) {
-  const response = await transport.requestJson(
-    "GET",
-    `${collectionPath(collection)}/graph/nodes`
-  );
+  const response = await transport.requestJson("GET", `${collectionPath(collection)}/graph/nodes`);
   throwOnError(response, `Collection '${collection}'`);
   const data = response.data;
   return { nodeIds: data.node_ids, count: data.count };
 }
-function idToNumber(id) {
-  return typeof id === "string" ? Number(id) : id;
+function idToGraphId(id) {
+  return id;
 }
 async function getNodeEdges(transport, collection, nodeId, options) {
   const params = new URLSearchParams();
@@ -1696,9 +1693,9 @@ async function getNodeEdges(transport, collection, nodeId, options) {
   const response = await transport.requestJson("GET", url);
   throwOnError(response, `Collection '${collection}'`);
   return (response.data?.edges ?? []).map((e) => ({
-    id: idToNumber(e.id),
-    source: idToNumber(e.source),
-    target: idToNumber(e.target),
+    id: e.id,
+    source: e.source,
+    target: e.target,
     label: e.label,
     properties: e.properties
   }));
@@ -1708,7 +1705,7 @@ async function getNodePayload(transport, collection, nodeId) {
   throwOnError(response, `Collection '${collection}'`);
   const data = response.data;
   return {
-    nodeId: idToNumber(data.node_id),
+    nodeId: idToGraphId(data.node_id),
     payload: data.payload
   };
 }
@@ -1732,7 +1729,7 @@ async function graphSearch(transport, collection, request2) {
   throwOnError(response, `Collection '${collection}'`);
   const items = (response.data?.results ?? []).map(
     (r) => ({
-      id: idToNumber(r.id),
+      id: idToGraphId(r.id),
       score: r.score,
       payload: r.payload
     })
@@ -1766,9 +1763,11 @@ async function storeSemanticFact(transport, collection, entry) {
         id: entry.id,
         vector: entry.embedding,
         payload: {
+          // Caller metadata is spread first so the reserved keys below
+          // (`_memory_type`, `text`) always win and cannot be clobbered.
+          ...entry.metadata,
           _memory_type: "semantic",
-          text: entry.text,
-          ...entry.metadata
+          text: entry.text
         }
       }]
     }
@@ -1788,16 +1787,20 @@ async function recordEpisodicEvent(transport, collection, event) {
         id,
         vector: event.embedding,
         payload: {
+          // Caller-supplied data/metadata is spread first so the reserved
+          // keys below (`_memory_type`, `event_type`, `timestamp`) always
+          // win and cannot be clobbered.
+          ...event.data,
+          ...event.metadata,
           _memory_type: "episodic",
           event_type: event.eventType,
-          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-          ...event.data,
-          ...event.metadata
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
         }
       }]
     }
   );
   throwOnError(response);
+  return id;
 }
 async function recallEpisodicEvents(transport, collection, embedding, k = 5) {
   return transport.searchVectors(collection, embedding, k, { _memory_type: "episodic" });
@@ -1810,16 +1813,21 @@ async function storeProceduralPattern(transport, collection, pattern) {
     {
       points: [{
         id,
+        vector: pattern.embedding,
         payload: {
+          // Caller metadata is spread first so the reserved keys below
+          // (`_memory_type`, `name`, `steps`) always win and cannot be
+          // clobbered.
+          ...pattern.metadata,
           _memory_type: "procedural",
           name: pattern.name,
-          steps: pattern.steps,
-          ...pattern.metadata
+          steps: pattern.steps
         }
       }]
     }
   );
   throwOnError(response);
+  return id;
 }
 async function matchProceduralPatterns(transport, collection, embedding, k = 5) {
   return transport.searchVectors(collection, embedding, k, { _memory_type: "procedural" });
@@ -1973,15 +1981,29 @@ async function addEdge(transport, collection, edge) {
   throwOnError(response, `Collection '${collection}'`);
 }
 function toGraphEdge(e) {
-  const toNum = (v) => typeof v === "string" ? Number(v) : v;
   return {
-    id: toNum(e.id),
-    source: toNum(e.source),
-    target: toNum(e.target),
+    id: e.id,
+    source: e.source,
+    target: e.target,
     label: e.label,
     properties: e.properties
   };
 }
+function toTraverseResponse(data) {
+  return {
+    results: data.results.map((r) => ({
+      targetId: r.target_id,
+      depth: r.depth,
+      path: r.path
+    })),
+    nextCursor: data.next_cursor ?? void 0,
+    hasMore: data.has_more,
+    stats: {
+      visited: data.stats.visited,
+      depthReached: data.stats.depth_reached
+    }
+  };
+}
 async function getEdges(transport, collection, options) {
   const queryParams = options?.label ? `?label=${encodeURIComponent(options.label)}` : "";
   const response = await transport.requestJson(
@@ -2005,20 +2027,7 @@ async function traverseGraph(transport, collection, request2) {
     }
   );
   throwOnError(response, `Collection '${collection}'`);
-  const data = response.data;
-  return {
-    results: data.results.map((r) => ({
-      targetId: r.target_id,
-      depth: r.depth,
-      path: r.path
-    })),
-    nextCursor: data.next_cursor ?? void 0,
-    hasMore: data.has_more,
-    stats: {
-      visited: data.stats.visited,
-      depthReached: data.stats.depth_reached
-    }
-  };
+  return toTraverseResponse(response.data);
 }
 async function getNodeDegree(transport, collection, nodeId) {
   const response = await transport.requestJson(
@@ -2053,20 +2062,7 @@ async function traverseParallel(transport, collection, request2) {
     }
   );
   throwOnError(response, `Collection '${collection}'`);
-  const data = response.data;
-  return {
-    results: data.results.map((r) => ({
-      targetId: r.target_id,
-      depth: r.depth,
-      path: r.path
-    })),
-    nextCursor: data.next_cursor ?? void 0,
-    hasMore: data.has_more,
-    stats: {
-      visited: data.stats.visited,
-      depthReached: data.stats.depth_reached
-    }
-  };
+  return toTraverseResponse(response.data);
 }
 
 // src/backends/query-backend.ts
@@ -2751,7 +2747,16 @@ var AgentMemoryClient = class {
     this.backend = backend;
     this.config = config;
   }
-  /** Configured embedding dimension (default: 384) */
+  /**
+   * Advisory embedding dimension passed at construction (default: 384).
+   *
+   * This value is **not** enforced and does not create or size any
+   * collection — the dimension that actually governs storage and search
+   * is the one fixed when the collection was created
+   * (`db.createCollection(name, { dimension, metric: 'cosine' })`).
+   * Embeddings you pass to `storeFact` / `recordEvent` / `learnProcedure`
+   * must match that collection dimension.
+   */
   get dimension() {
     return this.config?.dimension ?? 384;
   }
@@ -2763,7 +2768,7 @@ var AgentMemoryClient = class {
   async searchFacts(collection, embedding, k = 5) {
     return this.backend.searchSemanticMemory(collection, embedding, k);
   }
-  /** Record an episodic event */
+  /** Record an episodic event. Returns the generated point ID. */
   async recordEvent(collection, event) {
     return this.backend.recordEpisodicEvent(collection, event);
   }
@@ -2771,7 +2776,7 @@ var AgentMemoryClient = class {
   async recallEvents(collection, embedding, k = 5) {
     return this.backend.recallEpisodicEvents(collection, embedding, k);
   }
-  /** Store a procedural pattern */
+  /** Store a procedural pattern. Returns the generated point ID. */
   async learnProcedure(collection, pattern) {
     return this.backend.storeProceduralPattern(collection, pattern);
   }
@@ -2779,6 +2784,10 @@ var AgentMemoryClient = class {
   async recallProcedures(collection, embedding, k = 5) {
     return this.backend.matchProceduralPatterns(collection, embedding, k);
   }
+  /** Delete a memory entry (fact, event, or procedure) by its point ID. */
+  async deleteMemory(collection, id) {
+    return this.backend.delete(collection, id);
+  }
 };
 
 // src/client/validation.ts
@@ -2918,12 +2927,15 @@ function aggregate2(backend, queryString, params, options) {
 }
 
 // src/client/graph-methods.ts
+function isGraphNodeId(value) {
+  return typeof value === "number" || typeof value === "string";
+}
 function addEdge2(backend, collection, edge) {
   if (!edge.label || typeof edge.label !== "string") {
     throw new ValidationError("Edge label is required and must be a string");
   }
-  if (typeof edge.source !== "number" || typeof edge.target !== "number") {
-    throw new ValidationError("Edge source and target must be numbers");
+  if (!isGraphNodeId(edge.source) || !isGraphNodeId(edge.target)) {
+    throw new ValidationError("Edge source and target must be numbers or strings");
   }
   return backend.addEdge(collection, edge);
 }
@@ -2931,8 +2943,8 @@ function getEdges2(backend, collection, options) {
   return backend.getEdges(collection, options);
 }
 function traverseGraph2(backend, collection, request2) {
-  if (typeof request2.source !== "number") {
-    throw new ValidationError("Source node ID must be a number");
+  if (!isGraphNodeId(request2.source)) {
+    throw new ValidationError("Source node ID must be a number or string");
   }
   if (request2.strategy && !["bfs", "dfs"].includes(request2.strategy)) {
     throw new ValidationError("Strategy must be 'bfs' or 'dfs'");
@@ -2943,6 +2955,9 @@ function traverseParallel2(backend, collection, request2) {
   if (!Array.isArray(request2.sources) || request2.sources.length === 0) {
     throw new ValidationError("At least one source node ID is required");
   }
+  if (!request2.sources.every(isGraphNodeId)) {
+    throw new ValidationError("Source node IDs must be numbers or strings");
+  }
   return backend.traverseParallel(collection, request2);
 }
 function getNodeDegree2(backend, collection, nodeId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wiscale/velesdb-sdk",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "VelesDB TypeScript SDK: The Local Vector Database for AI & RAG. Microsecond semantic search in Browser & Node.js.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -14,7 +14,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
@@ -43,7 +44,7 @@
     "llm"
   ],
   "author": "Wiscale France",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
     "url": "https://github.com/cyberlife-coder/VelesDB.git",