mindgraph 0.12.0 → 0.14.0

package/dist/index.mjs

@@ -1,4 +1,7 @@
 // src/client.ts
+function seg(value) {
+  return encodeURIComponent(String(value));
+}
 var MindGraphError = class extends Error {
   constructor(message, status, body) {
     super(message);
@@ -19,15 +22,21 @@ var MindGraph = class {
     if (config.orgId) {
       this.headers["X-MindGraph-Org"] = config.orgId;
     }
+    this.telemetrySurface = config.telemetrySurface;
     this.maxRetries = config.maxRetries ?? 3;
     this.retryBackoffMs = config.retryBackoffMs ?? 1e3;
   }
   // ---- HTTP helpers ----
   async request(method, path, body) {
     const url = `${this.baseUrl}${path}`;
+    const requestId = createRequestId();
     const init = {
       method,
-      headers: this.headers
+      headers: {
+        ...this.headers,
+        "X-MindGraph-Request-ID": requestId,
+        ...this.telemetrySurface ? { "X-MindGraph-Surface": this.telemetrySurface } : {}
+      }
     };
     if (body !== void 0) {
       init.body = JSON.stringify(body);
@@ -262,6 +271,9 @@ var MindGraph = class {
   async memoryConfig(req) {
     return this.post("/memory/config", req);
   }
+  async memorySync(req) {
+    return this.post("/memory/sync", req);
+  }
   // ---- Agent Layer ----
   async plan(req) {
     return this.post("/agent/plan", req);
@@ -285,7 +297,7 @@ var MindGraph = class {
   }
   // ---- Node CRUD ----
   async getNode(uid) {
-    return this.get(`/node/${uid}`);
+    return this.get(`/node/${seg(uid)}`);
   }
   /**
    * Create a node via the low-level CRUD endpoint.
@@ -302,10 +314,10 @@ var MindGraph = class {
     return this.post("/node", { ...body, props });
   }
   async updateNode(uid, body) {
-    return this.patch(`/node/${uid}`, body);
+    return this.patch(`/node/${seg(uid)}`, body);
   }
   async deleteNode(uid) {
-    await this.del(`/node/${uid}`);
+    await this.del(`/node/${seg(uid)}`);
   }
   async batchDeleteNodes(params) {
     const body = {};
@@ -326,10 +338,10 @@ var MindGraph = class {
     return this.post("/nodes/delete", body);
   }
   async getNodeHistory(uid) {
-    return this.get(`/node/${uid}/history`);
+    return this.get(`/node/${seg(uid)}/history`);
   }
   async getNodeAtVersion(uid, version) {
-    return this.get(`/node/${uid}/history/${version}`);
+    return this.get(`/node/${seg(uid)}/history/${seg(version)}`);
   }
   // ---- Edge CRUD ----
   async addLink(body) {
@@ -350,13 +362,13 @@ var MindGraph = class {
     return this.post("/edge", { ...body, props });
   }
   async updateEdge(uid, body) {
-    return this.patch(`/edge/${uid}`, body);
+    return this.patch(`/edge/${seg(uid)}`, body);
   }
   async deleteEdge(uid) {
-    await this.del(`/edge/${uid}`);
+    await this.del(`/edge/${seg(uid)}`);
   }
   async getEdgeHistory(uid) {
-    return this.get(`/edge/${uid}/history`);
+    return this.get(`/edge/${seg(uid)}/history`);
   }
   /**
    * List edges filtered by source and/or target node.
@@ -405,7 +417,7 @@ var MindGraph = class {
     return this.get(`/nodes?${qs}`);
   }
   async getAgentNodes(agentId) {
-    return this.get(`/agent/${agentId}/nodes`);
+    return this.get(`/agent/${seg(agentId)}/nodes`);
   }
   // ---- Batch ----
   async batch(req) {
@@ -430,13 +442,13 @@ var MindGraph = class {
     return this.post("/embeddings/search-text", body);
   }
   async getEmbedding(uid) {
-    return this.get(`/node/${uid}/embedding`);
+    return this.get(`/node/${seg(uid)}/embedding`);
   }
   async setEmbedding(uid, vector) {
-    await this.request("PUT", `/node/${uid}/embedding`, { vector });
+    await this.request("PUT", `/node/${seg(uid)}/embedding`, { vector });
   }
   async deleteEmbedding(uid) {
-    await this.del(`/node/${uid}/embedding`);
+    await this.del(`/node/${seg(uid)}/embedding`);
   }
   // ---- Entity resolution ----
   async mergeEntities(body) {
@@ -446,7 +458,7 @@ var MindGraph = class {
     return this.post("/alias", body);
   }
   async getAliases(uid) {
-    return this.get(`/aliases/${uid}`);
+    return this.get(`/aliases/${seg(uid)}`);
   }
   async resolveAlias(text) {
     return this.get(`/resolve?text=${encodeURIComponent(text)}`);
@@ -569,18 +581,18 @@ var MindGraph = class {
     return this.get("/jobs");
   }
   async getJob(id) {
-    return this.get(`/jobs/${id}`);
+    return this.get(`/jobs/${seg(id)}`);
   }
   async cancelJob(id) {
-    return this.post(`/jobs/${id}/cancel`, {});
+    return this.post(`/jobs/${seg(id)}/cancel`, {});
   }
   /** Resume ingestion of a document that has failed chunks. */
   async resumeDocument(docUid, opts) {
-    return this.post(`/ingest/resume/${docUid}`, opts ?? {});
+    return this.post(`/ingest/resume/${seg(docUid)}`, opts ?? {});
   }
   /** Delete a document and all its chunks and extracted nodes. */
   async deleteDocument(uid) {
-    return this.del(`/ingest/document/${uid}`);
+    return this.del(`/ingest/document/${seg(uid)}`);
   }
   async cleanupOrphans() {
     return this.post("/ingest/cleanup", {});
@@ -604,27 +616,27 @@ var MindGraph = class {
   }
   /** Get a single wiki article by UID. */
   async getArticle(uid) {
-    return this.get(`/wiki/article/${uid}`);
+    return this.get(`/wiki/article/${seg(uid)}`);
   }
   /** Find the article that covers or summarizes a given entity/document UID. */
   async getArticleBySubject(subjectUid) {
     try {
-      return await this.get(`/wiki/article/by-subject/${subjectUid}`);
+      return await this.get(`/wiki/article/by-subject/${seg(subjectUid)}`);
     } catch {
       return null;
     }
   }
   /** Update an article's markdown content (user editing). */
   async updateArticle(uid, content) {
-    return this.patch(`/wiki/article/${uid}`, { content });
+    return this.patch(`/wiki/article/${seg(uid)}`, { content });
   }
   /** Trigger wiki compilation for a specific document. */
   async compileDocument(docUid) {
-    return this.post(`/wiki/compile/${docUid}`, {});
+    return this.post(`/wiki/compile/${seg(docUid)}`, {});
   }
   /** Trigger wiki compilation for a specific entity. */
   async compileEntity(entityUid) {
-    return this.post(`/wiki/compile/entity/${entityUid}`, {});
+    return this.post(`/wiki/compile/entity/${seg(entityUid)}`, {});
   }
   /** Backfill: compile articles for all documents and eligible entities. */
   async compileAll() {
@@ -645,7 +657,7 @@ var MindGraph = class {
     if (opts?.signals) q.set("signals", opts.signals);
     if (opts?.target_types) q.set("target_types", opts.target_types);
     const qs = q.toString();
-    return this.get(`/synthesis/signals/${projectUid}${qs ? `?${qs}` : ""}`);
+    return this.get(`/synthesis/signals/${seg(projectUid)}${qs ? `?${qs}` : ""}`);
   }
   /**
    * Spawn a background synthesis job for a project: mines signals,
@@ -655,7 +667,7 @@ var MindGraph = class {
    * Returns a `job_id` immediately; poll `getJob(id)` for progress.
    */
   async runSynthesis(projectUid) {
-    return this.post(`/synthesis/run/${projectUid}`, {});
+    return this.post(`/synthesis/run/${seg(projectUid)}`, {});
   }
   // ============================================================================
   // Operational Ontology Layer (Layer 7)
@@ -665,22 +677,22 @@ var MindGraph = class {
     return this.get("/v1/ontology/schemas");
   }
   async getOntologySchema(id) {
-    return this.get(`/v1/ontology/schemas/${id}`);
+    return this.get(`/v1/ontology/schemas/${seg(id)}`);
   }
   async createOntologySchema(req) {
     return this.post("/v1/ontology/schemas", req);
   }
   async updateOntologySchema(id, req) {
-    return this.patch(`/v1/ontology/schemas/${id}`, req);
+    return this.patch(`/v1/ontology/schemas/${seg(id)}`, req);
   }
   async activateOntologySchema(id) {
-    return this.post(`/v1/ontology/schemas/${id}/activate`, {});
+    return this.post(`/v1/ontology/schemas/${seg(id)}/activate`, {});
   }
   async deprecateOntologySchema(id) {
-    return this.post(`/v1/ontology/schemas/${id}/deprecate`, {});
+    return this.post(`/v1/ontology/schemas/${seg(id)}/deprecate`, {});
   }
   async archiveOntologySchema(id) {
-    return this.del(`/v1/ontology/schemas/${id}`);
+    return this.del(`/v1/ontology/schemas/${seg(id)}`);
   }
   /**
    * Kick off an LLM-driven schema proposal job.
@@ -691,47 +703,47 @@ var MindGraph = class {
     return this.post("/v1/ontology/propose-schema", req);
   }
   async testOntologySchema(id, opts) {
-    return this.post(`/v1/ontology/schemas/${id}/test`, opts ?? {});
+    return this.post(`/v1/ontology/schemas/${seg(id)}/test`, opts ?? {});
   }
   // ---- Schema sub-resources ----
   async addOntologyObjectType(schemaId, req) {
-    return this.post(`/v1/ontology/schemas/${schemaId}/object-types`, req);
+    return this.post(`/v1/ontology/schemas/${seg(schemaId)}/object-types`, req);
   }
   async updateOntologyObjectType(schemaId, typeId, req) {
     return this.patch(
-      `/v1/ontology/schemas/${schemaId}/object-types/${typeId}`,
+      `/v1/ontology/schemas/${seg(schemaId)}/object-types/${seg(typeId)}`,
       req
     );
   }
   async deleteOntologyObjectType(schemaId, typeId) {
     return this.del(
-      `/v1/ontology/schemas/${schemaId}/object-types/${typeId}`
+      `/v1/ontology/schemas/${seg(schemaId)}/object-types/${seg(typeId)}`
     );
   }
   async addOntologyRelationType(schemaId, req) {
-    return this.post(`/v1/ontology/schemas/${schemaId}/relation-types`, req);
+    return this.post(`/v1/ontology/schemas/${seg(schemaId)}/relation-types`, req);
   }
   async updateOntologyRelationType(schemaId, typeId, req) {
     return this.patch(
-      `/v1/ontology/schemas/${schemaId}/relation-types/${typeId}`,
+      `/v1/ontology/schemas/${seg(schemaId)}/relation-types/${seg(typeId)}`,
       req
     );
   }
   async deleteOntologyRelationType(schemaId, typeId) {
     return this.del(
-      `/v1/ontology/schemas/${schemaId}/relation-types/${typeId}`
+      `/v1/ontology/schemas/${seg(schemaId)}/relation-types/${seg(typeId)}`
     );
   }
   /** Generate inert semantic classifications for individual human review. */
   async analyzeOntologySemanticGuidance(schemaId) {
     return this.post(
-      `/v1/ontology/schemas/${schemaId}/semantic-guidance/analyze`,
+      `/v1/ontology/schemas/${seg(schemaId)}/semantic-guidance/analyze`,
       {}
     );
   }
   /** Read-only exact-identity collision audit; never merges graph data. */
   async auditOntologyDuplicates(schemaId) {
-    return this.post(`/v1/ontology/schemas/${schemaId}/duplicates/audit`, {});
+    return this.post(`/v1/ontology/schemas/${seg(schemaId)}/duplicates/audit`, {});
   }
   // ---- Proposals ----
   async listOntologyProposals(opts) {
@@ -747,19 +759,19 @@ var MindGraph = class {
     return this.get(`/v1/ontology/proposals${qs ? `?${qs}` : ""}`);
   }
   async getOntologyProposal(id) {
-    return this.get(`/v1/ontology/proposals/${id}`);
+    return this.get(`/v1/ontology/proposals/${seg(id)}`);
   }
   async patchOntologyProposal(id, req) {
-    return this.patch(`/v1/ontology/proposals/${id}`, req);
+    return this.patch(`/v1/ontology/proposals/${seg(id)}`, req);
   }
   async approveOntologyProposal(id, opts) {
-    return this.post(`/v1/ontology/proposals/${id}/approve`, opts ?? {});
+    return this.post(`/v1/ontology/proposals/${seg(id)}/approve`, opts ?? {});
   }
   async rejectOntologyProposal(id, reason) {
-    return this.post(`/v1/ontology/proposals/${id}/reject`, { reason });
+    return this.post(`/v1/ontology/proposals/${seg(id)}/reject`, { reason });
   }
   async applyOntologyProposal(id) {
-    return this.post(`/v1/ontology/proposals/${id}/apply`, {});
+    return this.post(`/v1/ontology/proposals/${seg(id)}/apply`, {});
   }
   async batchApproveOntologyProposals(ids, feedback) {
     return this.post("/v1/ontology/proposals/batch-approve", { ids, feedback });
@@ -771,24 +783,58 @@ var MindGraph = class {
   async queryOntology(req) {
     return this.post("/ontology/query", req);
   }
+  async queryDomainStructured(req) {
+    return this.post("/ontology/query/structured", req);
+  }
+  async queryRelatedDomainObjects(req) {
+    return this.queryDomainStructured({
+      schema_id: req.schema_id,
+      select: req.far_type,
+      ...req.project_uid ? { project_uid: req.project_uid } : {},
+      anchor: { type: req.entry_type, uid: req.uid },
+      path: [{
+        relation: req.relation,
+        entry_role: req.entry_role
+      }],
+      ...req.where ? { where: req.where } : {},
+      ...req.include_provenance ? { include: { provenance: true } } : {},
+      page: {
+        ...req.limit != null ? { limit: req.limit } : {},
+        ...req.offset != null ? { offset: req.offset } : {}
+      }
+    });
+  }
   /**
-   * Read-only agent tool descriptors generated from the active ontology
-   * schema(s). Each maps to a generic `/ontology` read endpoint with
-   * `object_type` bound. Used by the MCP server to expose typed per-object
-   * tools (`search_customers`, `summarize_customer`, …).
+   * Schema-qualified read-tool descriptors generated from every active
+   * ontology. Includes per-object discovery/point/context tools,
+   * relation-and-role-specific related tools, and one structured composite.
    */
   async listOntologyTools() {
     return this.get("/v1/ontology/tools");
   }
-  async getDomainObject(uid) {
-    return this.get(`/ontology/object/${uid}`);
-  }
-  async getDomainObjectContext(uid, depth) {
-    const qs = depth != null ? `?depth=${depth}` : "";
-    return this.get(`/ontology/object/${uid}/context${qs}`);
+  async getDomainObject(uid, binding) {
+    const query = new URLSearchParams();
+    if (binding) {
+      query.set("schema_id", binding.schema_id);
+      query.set("object_type", binding.object_type);
+      if (binding.project_uid) query.set("project_uid", binding.project_uid);
+    }
+    const suffix = query.size > 0 ? `?${query.toString()}` : "";
+    return this.get(`/ontology/object/${seg(uid)}${suffix}`);
+  }
+  async getDomainObjectContext(uid, depth, binding) {
+    const query = new URLSearchParams();
+    if (depth != null) query.set("depth", String(depth));
+    if (binding) {
+      query.set("schema_id", binding.schema_id);
+      query.set("object_type", binding.object_type);
+      if (binding.project_uid) query.set("project_uid", binding.project_uid);
+    }
+    const suffix = query.size > 0 ? `?${query.toString()}` : "";
+    return this.get(`/ontology/object/${seg(uid)}/context${suffix}`);
   }
   async getDomainObjectHistory(uid) {
-    return this.get(`/ontology/object/${uid}/history`);
+    return this.get(`/ontology/object/${seg(uid)}/history`);
   }
   async listDomainObjects(opts) {
     const q = new URLSearchParams();
@@ -828,6 +874,12 @@ var MindGraph = class {
     return this.post("/ontology/extract", req);
   }
 };
+function createRequestId() {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
 export {
   MindGraph,
   MindGraphError

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindgraph",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "TypeScript client for the MindGraph Cloud API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",