@wiscale/velesdb-sdk 1.18.0 → 2.0.0

package/dist/index.mjs

@@ -60,7 +60,7 @@ var WASM_CAPABILITIES = Object.freeze({
   agentMemory: false,
   streamInsert: false,
   pqTraining: false,
-  velesqlQuery: true,
+  velesqlQuery: false,
   collectionIntrospection: false
 });
 
@@ -298,20 +298,47 @@ async function wasmMultiQuerySearch(ctx, collectionName, vectors, options) {
   );
   return raw.map((r) => mapWasmResult(ctx, collection, r));
 }
-async function wasmQuery(ctx, collectionName, _queryString, params, _options) {
+var PURE_NEAR_QUERY = /^\s*select\s+\*\s+from\s+([a-z_]\w*)\s+where\s+vector\s+near\s+\$([a-z_]\w*)\s*(?:limit\s+(\d+))?\s*;?\s*$/i;
+function parsePureNearQuery(queryString) {
+  const match = PURE_NEAR_QUERY.exec(queryString);
+  if (!match) {
+    throw new VelesDBError(
+      `The WASM backend only executes pure top-k NEAR queries of the form "SELECT * FROM <collection> WHERE vector NEAR $param [LIMIT n]". WHERE predicates, JOIN, GROUP BY, MATCH, set operations and FUSION are not evaluated in WASM \u2014 use the REST backend (velesdb-server) for full VelesQL. Received: ${queryString}`,
+      "NOT_SUPPORTED"
+    );
+  }
+  const parsed = { from: match[1], param: match[2] };
+  if (match[3] !== void 0) {
+    parsed.limit = Number(match[3]);
+  }
+  return parsed;
+}
+function resolveQueryK(limit, requestedK) {
+  if (limit !== void 0) {
+    return limit;
+  }
+  return typeof requestedK === "number" && Number.isInteger(requestedK) && requestedK > 0 ? requestedK : 10;
+}
+async function wasmQuery(ctx, collectionName, queryString, params, _options) {
   const collection = ctx.getCollection(collectionName);
   if (!collection) {
     throw new NotFoundError(`Collection '${collectionName}'`);
   }
-  const paramsVector = params?.q;
+  const parsed = parsePureNearQuery(queryString);
+  if (parsed.from !== collectionName) {
+    throw new VelesDBError(
+      `Query targets collection '${parsed.from}' but was executed against '${collectionName}'.`,
+      "BAD_REQUEST"
+    );
+  }
+  const paramsVector = params?.[parsed.param];
   if (!Array.isArray(paramsVector) && !(paramsVector instanceof Float32Array)) {
     throw new VelesDBError(
-      "WASM query() expects params.q to contain the query embedding vector.",
+      `WASM query() expects params.${parsed.param} to contain the query embedding vector.`,
       "BAD_REQUEST"
     );
   }
-  const requestedK = params?.k;
-  const k = typeof requestedK === "number" && Number.isInteger(requestedK) && requestedK > 0 ? requestedK : 10;
+  const k = resolveQueryK(parsed.limit, params?.k);
   const raw = collection.store.query(
     paramsVector instanceof Float32Array ? paramsVector : new Float32Array(paramsVector),
     k
@@ -811,6 +838,12 @@ async function wasmRecordEpisodicEvent(_collection, _event) {
 async function wasmRecallEpisodicEvents(_collection, _embedding, _k) {
   wasmNotSupported("Agent memory");
 }
+async function wasmRecallRecentEvents(_collection, _since) {
+  wasmNotSupported("Agent memory");
+}
+async function wasmRecallOlderThanEvents(_collection, _before) {
+  wasmNotSupported("Agent memory");
+}
 async function wasmStoreProceduralPattern(_collection, _pattern) {
   wasmNotSupported("Agent memory");
 }
@@ -858,6 +891,18 @@ function wasmUpsertNodePayload(_c, _id, _p) {
 function wasmGraphSearch(_c, _r) {
   return Promise.resolve(wasmNotSupported("Graph search"));
 }
+function wasmRelate(_c, _req) {
+  return Promise.resolve(wasmNotSupported("Relation edges"));
+}
+function wasmUnrelate(_c, _id) {
+  return Promise.resolve(wasmNotSupported("Relation edge removal"));
+}
+function wasmGetRelations(_c, _id) {
+  return Promise.resolve(wasmNotSupported("Relation edges"));
+}
+function wasmSetTtlDurable(_c, _id, _ttl) {
+  return Promise.resolve(wasmNotSupported("Durable TTL"));
+}
 
 // src/backends/wasm.ts
 var WasmBackend = class {
@@ -1212,6 +1257,14 @@ var WasmBackend = class {
     this.ensureInitialized();
     return wasmRecallEpisodicEvents(c, e, k);
   }
+  async recallRecentEvents(c, since) {
+    this.ensureInitialized();
+    return wasmRecallRecentEvents(c, since);
+  }
+  async recallOlderThanEvents(c, before) {
+    this.ensureInitialized();
+    return wasmRecallOlderThanEvents(c, before);
+  }
   async storeProceduralPattern(c, p) {
     this.ensureInitialized();
     return wasmStoreProceduralPattern(c, p);
@@ -1273,16 +1326,43 @@ var WasmBackend = class {
     this.ensureInitialized();
     return wasmSparseSearchNamed(c, q, idx, o);
   }
+  async relate(c, req) {
+    this.ensureInitialized();
+    return wasmRelate(c, req);
+  }
+  async unrelate(c, edgeId) {
+    this.ensureInitialized();
+    return wasmUnrelate(c, edgeId);
+  }
+  async getRelations(c, pointId) {
+    this.ensureInitialized();
+    return wasmGetRelations(c, pointId);
+  }
+  async setTtlDurable(c, pointId, ttlSeconds) {
+    this.ensureInitialized();
+    return wasmSetTtlDurable(c, pointId, ttlSeconds);
+  }
 };
 
 // src/backends/crud-backend.ts
+var U64_MAX = 18446744073709551615n;
+function coerceDecimalStringId(id) {
+  if (!/^\d+$/.test(id)) return NaN;
+  const big = BigInt(id);
+  if (big > U64_MAX) return NaN;
+  return big > BigInt(Number.MAX_SAFE_INTEGER) ? id : Number(id);
+}
 function parseRestPointId(id) {
-  if (typeof id !== "number" || !Number.isFinite(id) || id < 0 || !Number.isInteger(id) || id > Number.MAX_SAFE_INTEGER) {
+  const coerced = typeof id === "string" ? coerceDecimalStringId(id) : id;
+  if (typeof coerced === "string") {
+    return coerced;
+  }
+  if (!Number.isFinite(coerced) || coerced < 0 || !Number.isInteger(coerced) || coerced > Number.MAX_SAFE_INTEGER) {
     throw new ValidationError(
-      `REST backend requires numeric u64-compatible IDs in JS safe integer range (0..${Number.MAX_SAFE_INTEGER}). Received: ${String(id)}`
+      `REST backend requires numeric u64-compatible IDs: a non-negative integer in the JS safe integer range (0..${Number.MAX_SAFE_INTEGER}) or a decimal string up to u64::MAX (${U64_MAX}). Received: ${String(id)}`
     );
   }
-  return id;
+  return coerced;
 }
 function sparseVectorToRestFormat(sv) {
   const result = {};
@@ -1737,6 +1817,31 @@ async function graphSearch(transport, collection, request2) {
   return { results: items };
 }
 
+// src/backends/scroll-backend.ts
+async function scroll(transport, collection, request2) {
+  const body = {};
+  if (request2?.cursor !== void 0) {
+    body.cursor = request2.cursor;
+  }
+  if (request2?.batchSize !== void 0) {
+    body.batch_size = request2.batchSize;
+  }
+  if (request2?.filter !== void 0) {
+    body.filter = request2.filter;
+  }
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/points/scroll`,
+    body
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  const data = response.data;
+  return {
+    points: data.points,
+    nextCursor: data.next_cursor
+  };
+}
+
 // src/backends/agent-memory-backend.ts
 var _idCounter = 0;
 var _lastTimestamp = 0;
@@ -1754,20 +1859,28 @@ function generateUniqueId() {
   }
   return _lastTimestamp * 1e3 + _idCounter;
 }
+function memoryIdToString(id) {
+  return String(id);
+}
+function nowUnixSeconds() {
+  return Math.floor(Date.now() / 1e3);
+}
 async function storeSemanticFact(transport, collection, entry) {
   const response = await transport.requestJson(
     "POST",
     `${collectionPath(collection)}/points`,
     {
       points: [{
-        id: entry.id,
+        id: parseRestPointId(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.
+          // (`_memory_type`, `content`) always win and cannot be clobbered.
           ...entry.metadata,
           _memory_type: "semantic",
-          text: entry.text
+          // `content` matches the core semantic store and the server/Python
+          // payload field (BREAKING: was `text` before this change).
+          content: entry.text
         }
       }]
     }
@@ -1778,7 +1891,8 @@ async function searchSemanticMemory(transport, collection, embedding, k = 5) {
   return transport.searchVectors(collection, embedding, k, { _memory_type: "semantic" });
 }
 async function recordEpisodicEvent(transport, collection, event) {
-  const id = generateUniqueId();
+  const id = event.id !== void 0 ? parseRestPointId(event.id) : generateUniqueId();
+  const timestamp = event.timestamp ?? nowUnixSeconds();
   const response = await transport.requestJson(
     "POST",
     `${collectionPath(collection)}/points`,
@@ -1794,19 +1908,21 @@ async function recordEpisodicEvent(transport, collection, event) {
           ...event.metadata,
           _memory_type: "episodic",
           event_type: event.eventType,
-          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          // NUMERIC unix-seconds, mirroring the core episodic store so
+          // recallRecent/recallOlderThan can range-filter on it.
+          timestamp
         }
       }]
     }
   );
   throwOnError(response);
-  return id;
+  return memoryIdToString(id);
 }
 async function recallEpisodicEvents(transport, collection, embedding, k = 5) {
   return transport.searchVectors(collection, embedding, k, { _memory_type: "episodic" });
 }
 async function storeProceduralPattern(transport, collection, pattern) {
-  const id = generateUniqueId();
+  const id = pattern.id !== void 0 ? parseRestPointId(pattern.id) : generateUniqueId();
   const response = await transport.requestJson(
     "POST",
     `${collectionPath(collection)}/points`,
@@ -1827,11 +1943,41 @@ async function storeProceduralPattern(transport, collection, pattern) {
     }
   );
   throwOnError(response);
-  return id;
+  return memoryIdToString(id);
 }
 async function matchProceduralPatterns(transport, collection, embedding, k = 5) {
   return transport.searchVectors(collection, embedding, k, { _memory_type: "procedural" });
 }
+function toEpisodicRecord(point) {
+  const payload = point.payload ?? {};
+  if (payload._memory_type !== "episodic") return void 0;
+  if (typeof payload.timestamp !== "number") return void 0;
+  return { id: String(point.id), timestamp: payload.timestamp, payload };
+}
+async function scrollEpisodicRecords(transport, collection) {
+  const records = [];
+  let cursor = null;
+  do {
+    const page = await scroll(transport, collection, {
+      cursor: cursor ?? void 0,
+      filter: { _memory_type: "episodic" }
+    });
+    for (const point of page.points) {
+      const record = toEpisodicRecord(point);
+      if (record !== void 0) records.push(record);
+    }
+    cursor = page.nextCursor;
+  } while (cursor !== null && cursor !== void 0);
+  return records;
+}
+async function recallRecentEvents(transport, collection, since) {
+  const records = await scrollEpisodicRecords(transport, collection);
+  return records.filter((r) => since === void 0 || r.timestamp >= since).sort((a, b) => b.timestamp - a.timestamp);
+}
+async function recallOlderThanEvents(transport, collection, before) {
+  const records = await scrollEpisodicRecords(transport, collection);
+  return records.filter((r) => r.timestamp < before).sort((a, b) => b.timestamp - a.timestamp);
+}
 
 // src/search-quality.ts
 function searchQualityToMode(quality) {
@@ -2064,6 +2210,64 @@ async function traverseParallel(transport, collection, request2) {
   throwOnError(response, `Collection '${collection}'`);
   return toTraverseResponse(response.data);
 }
+async function relate(transport, collection, req) {
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/relations`,
+    {
+      source: req.source,
+      target: req.target,
+      rel_type: req.relType,
+      properties: req.properties ?? {}
+    }
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  return { edgeId: response.data.edge_id };
+}
+async function unrelate(transport, collection, edgeId) {
+  const response = await transport.requestJson(
+    "DELETE",
+    `${collectionPath(collection)}/relations/${encodeURIComponent(String(edgeId))}`
+  );
+  if (response.error !== void 0) {
+    const { code, message } = response.error;
+    const err = parseVelesError(code, message);
+    if (err instanceof EdgeNotFoundError) {
+      return false;
+    }
+    if (code === "NOT_FOUND") {
+      return false;
+    }
+    throwOnError(response, `Collection '${collection}'`);
+  }
+  return true;
+}
+async function getRelations(transport, collection, pointId) {
+  const response = await transport.requestJson(
+    "GET",
+    `${collectionPath(collection)}/points/${encodeURIComponent(String(pointId))}/relations`
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  const raw = response.data;
+  return {
+    edges: raw.edges.map((e) => ({
+      id: e.id,
+      source: e.source,
+      target: e.target,
+      relType: e.rel_type,
+      properties: e.properties
+    })),
+    count: raw.count
+  };
+}
+async function setTtlDurable(transport, collection, pointId, ttlSeconds) {
+  const response = await transport.requestJson(
+    "PATCH",
+    `${collectionPath(collection)}/points/${encodeURIComponent(String(pointId))}/ttl`,
+    { ttl_seconds: ttlSeconds }
+  );
+  throwOnError(response, `Collection '${collection}'`);
+}
 
 // src/backends/query-backend.ts
 function isLikelyAggregationQuery(queryString) {
@@ -2196,31 +2400,6 @@ async function collectionSanity(transport, collection) {
   };
 }
 
-// src/backends/scroll-backend.ts
-async function scroll(transport, collection, request2) {
-  const body = {};
-  if (request2?.cursor !== void 0) {
-    body.cursor = request2.cursor;
-  }
-  if (request2?.batchSize !== void 0) {
-    body.batch_size = request2.batchSize;
-  }
-  if (request2?.filter !== void 0) {
-    body.filter = request2.filter;
-  }
-  const response = await transport.requestJson(
-    "POST",
-    `${collectionPath(collection)}/points/scroll`,
-    body
-  );
-  throwOnError(response, `Collection '${collection}'`);
-  const data = response.data;
-  return {
-    points: data.points,
-    nextCursor: data.next_cursor
-  };
-}
-
 // src/backends/admin-backend.ts
 function mapStatsResponse(data) {
   let columnStats;
@@ -2406,9 +2585,17 @@ async function streamInsert(transport, collection, docs) {
     }
   }
 }
+function requireSafeRangeId(restId) {
+  if (typeof restId === "string") {
+    throw new ValidationError(
+      `streamUpsertPoints requires ids in the JS safe integer range (0..${Number.MAX_SAFE_INTEGER}); use upsert/upsertBatch for string ids above it. Received: ${restId}`
+    );
+  }
+  return restId;
+}
 async function streamUpsertPoints(transport, collection, docs) {
   const ndjsonLines = docs.map((doc) => {
-    const restId = transport.parseRestPointId(doc.id);
+    const restId = requireSafeRangeId(transport.parseRestPointId(doc.id));
     const vector = toNumberArray(doc.vector);
     const point = {
       id: restId,
@@ -2599,6 +2786,22 @@ var RestBackend = class {
     this.ensureInitialized();
     return graphSearch(buildBaseTransport(this.httpConfig), c, r);
   }
+  async relate(c, req) {
+    this.ensureInitialized();
+    return relate(buildCrudTransport(this.httpConfig), c, req);
+  }
+  async unrelate(c, edgeId) {
+    this.ensureInitialized();
+    return unrelate(buildCrudTransport(this.httpConfig), c, edgeId);
+  }
+  async getRelations(c, pointId) {
+    this.ensureInitialized();
+    return getRelations(buildCrudTransport(this.httpConfig), c, pointId);
+  }
+  async setTtlDurable(c, pointId, ttlSeconds) {
+    this.ensureInitialized();
+    return setTtlDurable(buildCrudTransport(this.httpConfig), c, pointId, ttlSeconds);
+  }
   // Search
   async search(c, q, o) {
     this.ensureInitialized();
@@ -2731,6 +2934,14 @@ var RestBackend = class {
     this.ensureInitialized();
     return recallEpisodicEvents(buildAgentMemoryTransport(this.httpConfig, (col, emb, opts) => this.search(col, emb, opts)), c, e, k);
   }
+  async recallRecentEvents(c, since) {
+    this.ensureInitialized();
+    return recallRecentEvents(buildAgentMemoryTransport(this.httpConfig, (col, emb, opts) => this.search(col, emb, opts)), c, since);
+  }
+  async recallOlderThanEvents(c, before) {
+    this.ensureInitialized();
+    return recallOlderThanEvents(buildAgentMemoryTransport(this.httpConfig, (col, emb, opts) => this.search(col, emb, opts)), c, before);
+  }
   async storeProceduralPattern(c, p) {
     this.ensureInitialized();
     return storeProceduralPattern(buildAgentMemoryTransport(this.httpConfig, (col, emb, opts) => this.search(col, emb, opts)), c, p);
@@ -2768,15 +2979,29 @@ var AgentMemoryClient = class {
   async searchFacts(collection, embedding, k = 5) {
     return this.backend.searchSemanticMemory(collection, embedding, k);
   }
-  /** Record an episodic event. Returns the generated point ID. */
+  /** Record an episodic event. Returns the point ID (string, u64-safe). */
   async recordEvent(collection, event) {
     return this.backend.recordEpisodicEvent(collection, event);
   }
-  /** Recall episodic events */
+  /** Recall episodic events by vector similarity. */
   async recallEvents(collection, embedding, k = 5) {
     return this.backend.recallEpisodicEvents(collection, embedding, k);
   }
-  /** Store a procedural pattern. Returns the generated point ID. */
+  /**
+   * Recall episodic events most-recent-first, optionally bounded below by
+   * `since` (inclusive unix-seconds). Mirrors core `episodic.recent(since)`.
+   */
+  async recallRecent(collection, since) {
+    return this.backend.recallRecentEvents(collection, since);
+  }
+  /**
+   * Recall episodic events strictly older than `before` (unix-seconds),
+   * most-recent-first. Mirrors core `episodic.older_than(before)`.
+   */
+  async recallOlderThan(collection, before) {
+    return this.backend.recallOlderThanEvents(collection, before);
+  }
+  /** Store a procedural pattern. Returns the point ID (string, u64-safe). */
   async learnProcedure(collection, pattern) {
     return this.backend.storeProceduralPattern(collection, pattern);
   }
@@ -2784,7 +3009,12 @@ 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. */
+  /**
+   * Delete a memory entry (fact, event, or procedure) by its point ID.
+   *
+   * Accepts the `string` ids returned by `recordEvent` / `learnProcedure`
+   * (u64-safe decimal strings) as well as numeric ids.
+   */
   async deleteMemory(collection, id) {
     return this.backend.delete(collection, id);
   }
@@ -2818,11 +3048,10 @@ function validateDocument(doc, config) {
   validateRestPointId(doc.id, config);
 }
 function validateRestPointId(id, config) {
-  if (config.backend === "rest" && (typeof id !== "number" || !Number.isInteger(id) || id < 0 || id > Number.MAX_SAFE_INTEGER)) {
-    throw new ValidationError(
-      `REST backend requires numeric u64-compatible document IDs in JS safe integer range (0..${Number.MAX_SAFE_INTEGER})`
-    );
+  if (config.backend !== "rest") {
+    return;
   }
+  parseRestPointId(id);
 }
 
 // src/client/search-methods.ts
@@ -3003,6 +3232,40 @@ function graphSearch2(backend, collection, request2) {
   requireNonEmptyString(collection, "Collection");
   return backend.graphSearch(collection, request2);
 }
+function relate2(backend, collection, req) {
+  requireNonEmptyString(collection, "Collection");
+  if (!req.relType || typeof req.relType !== "string") {
+    throw new ValidationError("Relation type is required and must be a string");
+  }
+  if (!isGraphNodeId(req.source) || !isGraphNodeId(req.target)) {
+    throw new ValidationError("Source and target must be numbers or strings");
+  }
+  return backend.relate(collection, req);
+}
+function unrelate2(backend, collection, edgeId) {
+  requireNonEmptyString(collection, "Collection");
+  if (!isGraphNodeId(edgeId)) {
+    throw new ValidationError("Edge ID must be a number or string");
+  }
+  return backend.unrelate(collection, edgeId);
+}
+function getRelations2(backend, collection, pointId) {
+  requireNonEmptyString(collection, "Collection");
+  if (!isGraphNodeId(pointId)) {
+    throw new ValidationError("Point ID must be a number or string");
+  }
+  return backend.getRelations(collection, pointId);
+}
+function setTtlDurable2(backend, collection, pointId, ttlSeconds) {
+  requireNonEmptyString(collection, "Collection");
+  if (!isGraphNodeId(pointId)) {
+    throw new ValidationError("Point ID must be a number or string");
+  }
+  if (typeof ttlSeconds !== "number" || ttlSeconds < 0) {
+    throw new ValidationError("ttlSeconds must be a non-negative number");
+  }
+  return backend.setTtlDurable(collection, pointId, ttlSeconds);
+}
 
 // src/client.ts
 var VelesDB = class {
@@ -3300,6 +3563,22 @@ var VelesDB = class {
     this.ensureInitialized();
     return graphSearch2(this.backend, collection, request2);
   }
+  async relate(collection, req) {
+    this.ensureInitialized();
+    return relate2(this.backend, collection, req);
+  }
+  async unrelate(collection, edgeId) {
+    this.ensureInitialized();
+    return unrelate2(this.backend, collection, edgeId);
+  }
+  async getRelations(collection, pointId) {
+    this.ensureInitialized();
+    return getRelations2(this.backend, collection, pointId);
+  }
+  async setTtlDurable(collection, pointId, ttlSeconds) {
+    this.ensureInitialized();
+    return setTtlDurable2(this.backend, collection, pointId, ttlSeconds);
+  }
   // ========================================================================
   // Capabilities & Backend Info
   // ========================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wiscale/velesdb-sdk",
-  "version": "1.18.0",
+  "version": "2.0.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",
@@ -26,7 +26,7 @@
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
     "format": "prettier --write src",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.examples.json",
     "prepublishOnly": "npm run build"
   },
   "keywords": [