@thatopen/services 0.21.0 → 0.23.0

package/dist/cli.js

@@ -6795,6 +6795,120 @@ Object.assign(lookup, {
   io: lookup,
   connect: lookup
 });
+const DOCUMENT_SCHEMA = "thatopen/document@1";
+const DOCUMENT_FILE = "document.json";
+const versionTag$1 = () => `v-${Date.now()}`;
+function idOf$1(item) {
+  return String(item._id ?? item.id ?? "");
+}
+class ProjectDocuments {
+  constructor(client, projectId) {
+    this.client = client;
+    this.projectId = projectId;
+  }
+  /**
+   * The document's descriptor, read and validated, or null when the folder
+   * has none yet (an old folder, or a plain folder that is not a document).
+   */
+  async descriptor(folderId) {
+    const file = await this.#descriptorFile(folderId);
+    if (!file) return null;
+    const response = await this.client.downloadFile(file.id);
+    const text2 = await response.text();
+    if (!text2.trim()) return null;
+    let parsed;
+    try {
+      parsed = JSON.parse(text2);
+    } catch {
+      return null;
+    }
+    return normalize$1(parsed);
+  }
+  /**
+   * The first view whose format appears in `formats` — searched in the ORDER
+   * OF THE LIST, so the caller's preference wins (ask `['frag', 'ifc']` and a
+   * document carrying both answers the frag). Null when none matches: that is
+   * where an interface offers "Process".
+   */
+  async view(folderId, formats2) {
+    const descriptor = await this.descriptor(folderId);
+    if (!descriptor) return null;
+    for (const format2 of formats2) {
+      const match = descriptor.views.find((v) => v.format === format2);
+      if (match) return match;
+    }
+    return null;
+  }
+  /**
+   * Registers a renderable representation — a processor's last act. One view
+   * per format: an existing view of the same format is replaced (a re-run
+   * processor updates, it does not accumulate). The descriptor must exist;
+   * create it first with {@link setDescriptor}.
+   */
+  async addView(folderId, view) {
+    const descriptor = await this.descriptor(folderId);
+    if (!descriptor) {
+      throw new Error(
+        "This folder has no document descriptor yet: call setDescriptor first."
+      );
+    }
+    descriptor.views = [
+      ...descriptor.views.filter((v) => v.format !== view.format),
+      view
+    ];
+    await this.setDescriptor(folderId, descriptor);
+  }
+  /** Writes the descriptor, creating or replacing `document.json`. */
+  async setDescriptor(folderId, descriptor) {
+    const value2 = {
+      ...descriptor,
+      schema: DOCUMENT_SCHEMA,
+      views: descriptor.views ?? []
+    };
+    const blob = new Blob([JSON.stringify(value2)], {
+      type: "application/json"
+    });
+    const existing = await this.#descriptorFile(folderId);
+    if (existing) {
+      await this.client.updateFile(existing.id, {
+        file: blob,
+        versionTag: versionTag$1()
+      });
+      return;
+    }
+    await this.client.createFile({
+      file: blob,
+      name: DOCUMENT_FILE,
+      versionTag: versionTag$1(),
+      parentFolderId: folderId,
+      projectId: this.projectId
+    });
+  }
+  async #descriptorFile(folderId) {
+    const items2 = await this.client.listFiles({ folderId });
+    const found = items2.find(
+      (item) => String(item.name ?? "") === DOCUMENT_FILE
+    );
+    return found ? { id: idOf$1(found) } : void 0;
+  }
+}
+function normalize$1(parsed) {
+  if (!parsed || typeof parsed !== "object") return null;
+  const raw = parsed;
+  if (raw.schema !== DOCUMENT_SCHEMA) return null;
+  if (typeof raw.name !== "string") return null;
+  const views = Array.isArray(raw.views) ? raw.views.filter(
+    (v) => !!v && typeof v === "object" && typeof v.fileId === "string" && typeof v.format === "string"
+  ) : [];
+  const native = raw.native;
+  const hasNative = !!native && typeof native === "object" && typeof native.fileId === "string" && typeof native.format === "string";
+  return {
+    schema: DOCUMENT_SCHEMA,
+    name: raw.name,
+    ...hasNative ? { native: { fileId: native.fileId, format: native.format } } : {},
+    views
+  };
+}
 class StaleHistoryError extends Error {
   constructor(expectedGuid, actualGuid) {
     super(
@@ -6811,6 +6925,7 @@ const OPS_FILE = "revitflow_ops.json";
 const OPS_SCHEMA = "revitflow/ops@1";
 const LEGACY_MODEL_FILE = "revitflow_model.frag";
 const INTERNAL_PREFIX = "revitflow_";
+const LOCKS_ANCHOR = "bimterop-locks-anchor";
 const versionTag = () => `v-${Date.now()}`;
 function childrenOf(folders, parentId) {
   return folders.filter((f) => String(f.parentId ?? "") === parentId);
@@ -6837,10 +6952,22 @@ class ProjectHistory {
       const name = String(folder.name ?? "");
       const dash = name.indexOf("-");
       if (dash <= 0) continue;
+      const files = await this.client.listFiles({
+        folderId: idOf(folder)
+      });
+      const names2 = files.map(
+        (f) => String(f.name ?? "")
+      );
+      const model = names2.find((n) => n === LEGACY_MODEL_FILE) ?? names2.find(
+        (n) => n.endsWith(".frag") && !n.startsWith(INTERNAL_PREFIX)
+      );
+      const hasAny = names2.includes(HISTORY_FILE) || names2.includes(OPS_FILE) || !!model;
       docs.push({
         source: name.slice(0, dash),
         docId: name.slice(dash + 1),
-        modelName: void 0
+        folderId: idOf(folder),
+        modelName: model,
+        ...hasAny ? {} : { empty: true }
       });
     }
     return docs;
@@ -6922,6 +7049,105 @@ class FlowDoc {
     const response = await this.client.downloadFile(file.id);
     return await response.blob();
   }
+  /** The document folder's item id — the id the CDE knows this document by. */
+  async folderId() {
+    return await this.#folder(false);
+  }
+  // ─── The document descriptor ───────────────────────────────────────────────
+  /**
+   * The document descriptor (`document.json`), or null when the folder does
+   * not carry one yet — an old folder from before descriptors existed.
+   */
+  async descriptor() {
+    return await this.#documents.descriptor(await this.#folder(false));
+  }
+  /**
+   * The first view whose format appears in `formats`, searched in the order
+   * of the list (the caller's preference wins). Falls back to the visible
+   * model .frag on a descriptor-less folder, so old documents keep viewing.
+   */
+  async view(formats2) {
+    const folderId = await this.#folder(false);
+    const descriptor = await this.#documents.descriptor(folderId);
+    if (descriptor) {
+      for (const format2 of formats2) {
+        const match = descriptor.views.find((v) => v.format === format2);
+        if (match) return match;
+      }
+      return null;
+    }
+    if (!formats2.includes("frag")) return null;
+    const model = await this.#modelFile();
+    return model ? { fileId: model.id, format: "frag" } : null;
+  }
+  /**
+   * Registers a renderable representation, creating the descriptor when the
+   * folder predates them (named after the model file, or the folder itself).
+   * One view per format: a same-format view is replaced, not accumulated.
+   */
+  async addView(view) {
+    const folderId = await this.#folder(true);
+    const descriptor = await this.#documents.descriptor(folderId);
+    if (descriptor) {
+      await this.#documents.addView(folderId, view);
+      return;
+    }
+    const model = await this.#modelFile();
+    await this.#documents.setDescriptor(folderId, {
+      name: model?.name.replace(/\.frag$/, "") ?? this.#folderName,
+      views: [view]
+    });
+  }
+  // ─── Ownership (element locks) ─────────────────────────────────────────────
+  /**
+   * Who currently holds which elements, read from the lock registry the
+   * native plugins arbitrate through. Read-only: claiming and releasing stay
+   * with the plugins. Empty when nobody holds anything (or the document has
+   * no lock anchor yet). Arbitration is applied: a key contested by two
+   * claims counts only for the earliest one, matching the plugins' rule.
+   */
+  async ownership() {
+    const anchor = await this.#file(LOCKS_ANCHOR);
+    if (!anchor) return [];
+    const metas = await this.client.getHiddenFilesByParent(anchor.id);
+    const claims = await Promise.all(
+      metas.map(async (meta) => {
+        try {
+          const id2 = idOf(meta);
+          const response = await this.client.downloadHiddenFile(id2);
+          const parsed = JSON.parse(await response.text());
+          if (!parsed || typeof parsed !== "object") return null;
+          if (!("revitflowlock" in parsed)) return null;
+          if (!Array.isArray(parsed.keys)) return null;
+          return {
+            owner: String(parsed.user ?? ""),
+            keys: parsed.keys.filter((k) => typeof k === "string")
+          };
+        } catch {
+          return null;
+        }
+      })
+    );
+    const taken = /* @__PURE__ */ new Set();
+    const byOwner = /* @__PURE__ */ new Map();
+    for (const claim of claims) {
+      if (!claim) continue;
+      for (const key of claim.keys) {
+        if (!key || taken.has(key)) continue;
+        taken.add(key);
+        const list = byOwner.get(claim.owner) ?? [];
+        list.push(key);
+        byOwner.set(claim.owner, list);
+      }
+    }
+    return [...byOwner.entries()].map(([owner, elements]) => ({
+      owner,
+      elements
+    }));
+  }
+  get #documents() {
+    return new ProjectDocuments(this.client, this.project.projectId);
+  }
   // ─── Writing versions ─────────────────────────────────────────────────────
   /**
    * Appends one version: uploads the geometry it carries, then the updated
@@ -7003,6 +7229,7 @@ class FlowDoc {
     const indexFile = await this.#file(OPS_FILE);
     const suggestion = {
       opId: input.opId ?? mintGuid(),
+      to: input.to ?? this.source,
       title: input.title,
       verb: input.verb,
       author: input.author,
@@ -7260,14 +7487,39 @@ class Recipes {
     return this.#registry.get(name);
   }
   /**
-   * Runs a recipe WITHOUT queueing anything: the dry pass. Returns the
-   * recipe's result — title, tallies per rule, targets — so an app can show
-   * what would be proposed before anybody confirms. The payload it may have
-   * built is discarded along with its opId.
+   * Runs a recipe WITHOUT queueing anything: the dry pass. Returns a
+   * {@link RecipePlan} — the result to show (title, tallies, targets) plus
+   * everything {@link queue} needs to queue EXACTLY this, payload and opId
+   * included, with no second run. Discard it and the plan never happened.
    */
   async plan(name, options) {
-    const { result } = await this.#execute(name, options);
-    return result;
+    const { base, opId, result } = await this.#execute(name, options);
+    return {
+      opId,
+      projectId: options.projectId,
+      target: options.target,
+      ...base?.guid ? { baseCommitGuid: base.guid } : {},
+      result
+    };
+  }
+  /**
+   * Queues exactly what {@link plan} planned: same opId, same payload, no
+   * second execution. The pair plan → confirm → queue is the UI flow; `run`
+   * is the one-shot shortcut.
+   */
+  async queue(plan, options) {
+    const targetDoc = this.client.history(plan.projectId).doc(plan.target.source, plan.target.docId);
+    const suggestion = await targetDoc.suggest({
+      opId: plan.opId,
+      title: plan.result.title,
+      verb: plan.result.verb,
+      author: options.author,
+      payload: plan.result.payload,
+      targets: plan.result.targets,
+      userId: options.userId,
+      baseCommitGuid: plan.baseCommitGuid
+    });
+    return { suggestion, result: plan.result };
   }
   /**
    * Runs a recipe and queues its suggestion on the target document. Safe to
@@ -8320,7 +8572,15 @@ return main;`);
       console.log(e);
     });
   }
-  // ─── History & Recipes ───────────────────────────────────────────
+  // ─── Documents, History & Recipes ────────────────────────────────
+  /**
+   * A project's documents. Every document is a FOLDER holding its files plus
+   * a `document.json` descriptor naming the document, its native form and its
+   * renderable views. See `src/core/documents.ts` for the model and schema.
+   */
+  documents(projectId) {
+    return new ProjectDocuments(this, projectId);
+  }
   /**
    * A project's history of connected documents (Revit models, AutoCAD
    * drawings…): their version timelines and their change requests. See