@thatopen/services 0.0.4 → 0.0.6

package/src/built-in/CDEManager/examples/FileOperations/example.ts

@@ -0,0 +1,295 @@
+/* MD
+  ## File operations — inline edit, rename, view, download, archive
+  ---
+  BIM coordinators reviewing a model drop repeat the same small actions throughout
+  their session: correcting a discipline tag that changed after a scope revision,
+  renaming a file to match the agreed convention, opening it alongside the structural
+  model to check for clashes, handing it off to a sub-consultant, or removing a
+  superseded version from the live set. If every panel in the platform handles these
+  separately, two panels looking at the same file at the same time can show
+  contradictory states — one says "uploading", another still shows the old name.
+
+  CDEManager gives all of these operations a single shared state. Every action moves
+  through a known transition so any part of the platform — the file table, the viewer,
+  the side panel — reacts to the same source of truth without coordinating with every
+  other panel individually.
+
+  This tutorial covers selecting files and editing a metadata value inline; cancelling
+  an in-progress edit; committing the edit and reading the updated value back from the
+  state; renaming a file optimistically and observing the local update; opening files
+  in the viewer, adding a second file to the active view, simulating load completion,
+  and removing files from the view one at a time; closing the viewer while keeping the
+  selection intact; and, with live credentials, downloading a selection and archiving a
+  file through the state machine.
+
+  By the end, you'll have a working demonstration of every per-file state machine flow
+  — inline edit, rename, viewer, download, and archive — with all mock-data flows
+  running without any backend connection.
+*/
+
+import * as OBC from "@thatopen/components";
+// In production platform apps, CDEManager is loaded through the platform client:
+//   const cde = await client.initBuiltInComponent(CDEManager.uuid, components);
+// Here we import directly from source for local testing.
+import { CDEManager } from "../../index";
+import type { CDEFile } from "../../src/types";
+
+/* MD
+  ### 🛠️ Setting up
+  Most flows in this example run against mock data without a backend connection.
+  However, operations like editing metadata and renaming files are permission-gated —
+  the platform normally loads those permissions when the app starts. We simulate that
+  startup step here so the demo flows work in isolation. We also register viewer groups
+  before setting any files because the transition into the viewer validates the group
+  configuration at the moment of the event.
+*/
+
+const components = new OBC.Components();
+const cde = components.get(CDEManager);
+
+const output = document.getElementById("output") as HTMLPreElement;
+const log = (msg: string) => { console.log(msg); output.textContent += msg + "\n"; };
+
+// The "ifc/frag" group allows multiple files open at the same time; "pdf" does not.
+cde.viewerGroups = [
+  { extensions: ["ifc", "frag"], multiple: true },
+  { extensions: ["pdf"] },
+];
+
+// Simulate the platform startup step that loads user permissions.
+// Without this, permission-gated events (edit, rename, archive) are silently ignored.
+cde.ctx = {
+  client: {
+    checkPermissionBatch: async () => Array(5).fill({ hasPermission: true }),
+    getProjectData: async () => ({ project: { title: "" }, users: [] }),
+    listFolders: async () => [],
+    updateFile: async (id: string) => ({ item: { _id: id } }),
+    updateFileVersionMetadata: async () => ({}),
+  } as any,
+  projectId: "mock",
+};
+await cde.loadFolders();
+// Clear the context after loading permissions — mock flows don't make API calls.
+// With a live client, operations like rename would also confirm via onRenameCompleted.
+cde.ctx = undefined;
+
+const now = new Date();
+const mockFiles: CDEFile[] = [
+  {
+    _id: "f1", name: "column.ifc", folderId: null,
+    createdBy: "alice", createdAt: now,
+    metadata: { discipline: "STR", phase: "DD" },
+  } as CDEFile,
+  {
+    _id: "f2", name: "foundations.ifc", folderId: null,
+    createdBy: "bob", createdAt: now,
+    metadata: { discipline: "STR", phase: "CD" },
+  } as CDEFile,
+];
+cde.files = mockFiles;
+
+cde.onMachineStateChanged.add((s) => log(`  → ${s.kind}`));
+cde.onFilesChanged.add((files) => log(`  [onFilesChanged] ${files.length} file(s)`));
+cde.onRenameCompleted.add(({ success, error }) =>
+  log(success ? "  [onRenameCompleted] server confirmed" : `  [onRenameCompleted] rolled back — ${error}`)
+);
+cde.onDownloadReady.add(({ blob, filename }) =>
+  log(`  [onDownloadReady] "${filename}" — ${blob.size} bytes`)
+);
+
+/* MD
+  ### ✏️ Inline metadata edit
+  When a coordinator spots a wrong discipline tag, they should be able to correct it
+  right in the file row rather than navigating to a separate form. The edit stays
+  pending — visible as an unsaved diff — so the UI can show exactly what will change
+  before anything is written.
+
+  Entering the edit state carries the selected files along, so the form always knows
+  which file it is editing. Cancelling discards all pending values and returns to the
+  exact same selection — nothing is sent to the backend.
+*/
+
+log("\n--- inline edit: cancel ---");
+cde.sendMachineEvent({ type: "SELECT", files: [mockFiles[0]] });
+cde.sendMachineEvent({ type: "START_EDIT" });
+cde.sendMachineEvent({ type: "UPDATE_METADATA", key: "phase", value: "SD" });
+
+if (cde.machineState.kind === "editing") {
+  log(`  pending phase: ${cde.machineState.pendingMetadata.phase}`);
+}
+
+cde.sendMachineEvent({ type: "CANCEL_EDIT" });
+// The original mockFiles[0] reference is unchanged — nothing was applied.
+log(`  phase after cancel: ${mockFiles[0].metadata.phase}`);
+
+/* MD
+  Committing the edit applies the pending values to the file in memory and returns to
+  the selection, with the file already reflecting its new values. With a live backend,
+  the changes are persisted before the transition completes; without one, the local
+  update still happens. Either way, the updated file is in the machine state's
+  selection — not in the original array reference.
+*/
+
+log("\n--- inline edit: save ---");
+// Re-enter from the current "selected" state.
+cde.sendMachineEvent({ type: "START_EDIT" });
+cde.sendMachineEvent({ type: "UPDATE_METADATA", key: "phase", value: "SD" });
+cde.sendMachineEvent({ type: "SAVE" });
+
+// _saveFileMetadata without a client applies the edit locally and returns synchronously.
+if (cde.machineState.kind === "selected") {
+  log(`  phase after save: ${cde.machineState.files[0].metadata.phase}`);
+}
+
+/* MD
+  ### 🏷️ Optimistic rename
+  Renaming a file can't wait for a server round-trip — the user should see the new
+  name appear immediately. The rename applies locally the moment it is triggered, then
+  a confirmation arrives once the backend has saved it. If the server rejects the
+  change, the name reverts automatically and a rollback event is fired so the UI can
+  notify the user.
+
+  Without a live backend, the local rename still applies and the file list updates —
+  only the server confirmation step is skipped, so the rollback path is never reached.
+*/
+
+log("\n--- rename immediate ---");
+cde.sendMachineEvent({ type: "RENAME_FILE_IMMEDIATE", fileId: "f1", name: "column-v2.ifc" });
+
+const renamedFile = cde.files.find(f => f._id === "f1")!;
+log(`  local name: ${renamedFile.name}`);
+// onRenameCompleted fires only with a live client — skipped here.
+
+// Restore the original name so the view-flow demo works with "column.ifc".
+cde.sendMachineEvent({ type: "RENAME_FILE_IMMEDIATE", fileId: "f1", name: "column.ifc" });
+
+/* MD
+  ### 👁️ Viewer
+  Opening files in the viewer is a state transition, not a direct method call. This
+  keeps the viewer component decoupled from the file table — any part of the platform
+  can request a view by sending an event, and the viewer just reacts to the state
+  change. No direct reference from one component to the other is required.
+
+  When a viewer group supports multiple files, a second can be added while the first
+  is still loading. Each file tracks its own load status independently, so the viewer
+  can show a spinner per model without needing its own state management.
+*/
+
+log("\n--- view: open and add ---");
+cde.sendMachineEvent({ type: "SELECT", files: [mockFiles[0]] });
+cde.sendMachineEvent({ type: "VIEW" });
+
+// The viewer calls this once its geometry is ready — here we simulate it.
+cde.sendMachineEvent({ type: "SET_VIEW_FILE_STATUS", fileId: "f1", status: "ready" });
+
+cde.sendMachineEvent({ type: "ADD_TO_VIEW", file: mockFiles[1] });
+
+if (cde.machineState.kind === "viewing") {
+  log(`  files in viewer: ${cde.machineState.files.length}`);
+  log(`  f1: ${cde.machineState.fileStatus["f1"]}, f2: ${cde.machineState.fileStatus["f2"]}`);
+}
+
+cde.sendMachineEvent({ type: "SET_VIEW_FILE_STATUS", fileId: "f2", status: "ready" });
+
+/* MD
+  Removing the last file from the viewer closes it entirely — the state moves to idle
+  rather than back to a selection, since there is nothing left to select. Removing one
+  of several files leaves the rest open.
+
+  Alternatively, closing the viewer explicitly returns to the selection state with the
+  same files still highlighted — useful when the user wants to go back to the file
+  table without losing which row was active.
+*/
+
+log("\n--- view: remove one by one ---");
+cde.sendMachineEvent({ type: "REMOVE_FROM_VIEW", fileId: "f1" });
+log(`  after removing f1: ${cde.machineState.kind}`);
+
+cde.sendMachineEvent({ type: "REMOVE_FROM_VIEW", fileId: "f2" });
+log(`  after removing last: ${cde.machineState.kind}`);
+
+log("\n--- view: close keeps selection ---");
+cde.sendMachineEvent({ type: "SELECT", files: [mockFiles[0]] });
+cde.sendMachineEvent({ type: "VIEW" });
+cde.sendMachineEvent({ type: "CLOSE_VIEW" });
+log(`  state: ${cde.machineState.kind}`);
+if (cde.machineState.kind === "selected") {
+  log(`  selection preserved: ${cde.machineState.files.length} file(s)`);
+}
+
+/* MD
+  ### 🌐 Download and archive (requires credentials)
+  Download has to fetch file content from the backend, and archive needs the account
+  to have delete access on the project — so both flows require live credentials. Pass
+  them as query parameters to run this section:
+
+    example.html?accessToken=<token>&apiUrl=https://...&projectId=<id>
+
+  We create a throwaway file here so the demo is self-contained and leaves no
+  permanent changes in the project.
+*/
+
+const params = new URLSearchParams(location.search);
+const accessToken = params.get("accessToken");
+const apiUrl = params.get("apiUrl");
+const projectId = params.get("projectId");
+
+if (accessToken && apiUrl && projectId) {
+  const { EngineServicesClient } = await import("thatopen-services");
+  const client = new EngineServicesClient(accessToken, apiUrl);
+  // Replace the mock context with the real one.
+  cde.ctx = { client, projectId };
+
+  // loadFolders also resolves user permissions — needed before archive.
+  await cde.loadFolders();
+  log(`\nProject: "${cde.projectName}", canDelete: ${cde.userPermissions.canDelete}`);
+
+  // Create a throwaway file so the demo doesn't touch existing project data.
+  const blob = new Blob([JSON.stringify({ demo: true })], { type: "application/json" });
+  const { item } = await client.createFile({
+    file: blob, name: `__example-test__-${Date.now()}.json`, versionTag: "v1", projectId,
+  });
+  const liveFile: CDEFile = {
+    ...item,
+    createdAt: new Date(item.createdAt),
+    createdBy: "",
+    metadata: {},
+  } as CDEFile;
+  cde.files = [liveFile];
+  log(`Created test file: ${item._id}`);
+
+  // --- Download ---
+  log("\n--- download ---");
+  cde.sendMachineEvent({ type: "SELECT", files: [liveFile] });
+  // onDownloadReady fires with { blob, filename } — multiple selected files are zipped.
+  await new Promise<void>(resolve => {
+    cde.onDownloadReady.add(() => resolve());
+    cde.sendMachineEvent({ type: "DOWNLOAD" });
+  });
+
+  // --- Archive ---
+  // ARCHIVE_FILE is silently ignored if the account lacks delete permission.
+  if (cde.userPermissions.canDelete) {
+    log("\n--- archive ---");
+    cde.sendMachineEvent({ type: "SELECT", files: [liveFile] });
+    await new Promise<void>(resolve => {
+      cde.onMachineStateChanged.add((s) => {
+        if (s.kind === "idle" || s.kind === "error") resolve();
+      });
+      cde.sendMachineEvent({ type: "ARCHIVE_FILE" });
+    });
+
+    if (cde.machineState.kind === "error") {
+      log(`  archive failed: ${cde.machineState.reason}`);
+      cde.sendMachineEvent({ type: "DISMISS" });
+      await client.archiveFile(item._id as string);
+    } else {
+      log(`  archived. Files in cde: ${cde.files.length}`);
+    }
+  } else {
+    log("Archive skipped — no delete permission. Cleaning up directly.");
+    await client.archiveFile(item._id as string);
+  }
+} else {
+  log("\nDownload and archive skipped — pass ?accessToken=&apiUrl=&projectId= to run.");
+}

package/src/built-in/CDEManager/examples/FileTransfers/example.ts

@@ -0,0 +1,210 @@
+/* MD
+  ## File uploads, versioning, and the download cache
+  ---
+  A site coordinator drops a batch of files onto the CDE every Monday after the
+  weekend review: some are entirely new models, some are revised versions of files
+  already in the project, and sometimes the metadata group they upload into should
+  be stamped automatically onto the new files. If the platform makes the coordinator
+  sort this out manually, it slows the handoff and introduces naming errors. And if
+  an upload fails halfway through a batch, the file table should land in a safe state
+  rather than freeze at a loading spinner.
+
+  CDEManager's upload method compares each incoming file against the current list by
+  base name and extension. Files with no match are created from scratch; files that
+  match an existing entry produce a new version instead. When a metadata group is
+  active, the group's values are stamped onto every file in the batch without any
+  extra action from the user. The state machine moves through a dedicated uploading
+  state so any component in the platform can show a progress indicator by reading a
+  single source of truth.
+
+  This tutorial covers uploading new files and reading the result from the
+  upload-completed event; uploading a file whose name matches an existing entry and
+  confirming it is versioned rather than duplicated; attaching metadata automatically
+  when the upload runs inside an active metadata group; recovering cleanly from an
+  upload error through the state machine; and reading file content through the
+  in-memory cache that avoids re-fetching the same version twice.
+
+  By the end, you'll have a working demonstration of the full upload lifecycle —
+  create, version, auto-metadata, error recovery — plus the cache hit and miss
+  behavior that the viewer relies on when loading models.
+*/
+
+import * as OBC from "@thatopen/components";
+// In production platform apps, CDEManager is loaded through the platform client:
+//   const cde = await client.initBuiltInComponent(CDEManager.uuid, components);
+// Here we import directly from source for local testing.
+import { CDEManager } from "../../index";
+import type { CDEFile } from "../../src/types";
+
+/* MD
+  ### 🛠️ Setting up
+  All flows in this example use a minimal mock client so they run without a backend
+  connection. Unlike mock flows that clear the client context after loading permissions,
+  upload and download operations require an active client throughout — so the context
+  stays set for the full example.
+*/
+
+const components = new OBC.Components();
+const cde = components.get(CDEManager);
+
+const output = document.getElementById("output") as HTMLPreElement;
+const log = (msg: string) => { console.log(msg); output.textContent += msg + "\n"; };
+
+let fileCounter = 0;
+// Track created version records so the versioning demo can find them.
+const mockVersions: Record<string, { tag: string }[]> = {};
+
+const mockClient = {
+  checkPermissionBatch: async () => Array(5).fill({ hasPermission: true }),
+  getProjectData: async () => ({ project: { title: "Demo Project" }, users: [] }),
+  listFolders: async () => [],
+  createFile: async ({ name, versionTag, parentFolderId }: any) => {
+    const id = `file-${fileCounter++}`;
+    mockVersions[id] = [{ tag: versionTag }];
+    return {
+      item: { _id: id, name, folderId: parentFolderId ?? null, createdAt: new Date().toISOString(), createdBy: "mock-user", itemType: "FILE" },
+      version: { tag: versionTag },
+    };
+  },
+  listVersions: async (fileId: string) => mockVersions[fileId] ?? [],
+  createVersion: async (fileId: string, _file: File, tag: string) => {
+    mockVersions[fileId] = [...(mockVersions[fileId] ?? []), { tag }];
+    return { tag };
+  },
+  updateFileVersionMetadata: async () => ({}),
+  downloadFile: async (_id: string) => ({ arrayBuffer: async () => new ArrayBuffer(4096) }),
+  archiveFile: async () => ({}),
+};
+
+cde.ctx = { client: mockClient as any, projectId: "mock" };
+await cde.loadFolders();
+
+cde.onMachineStateChanged.add((s) => log(`  → ${s.kind}`));
+
+/* MD
+  ### 📤 Uploading new files
+  Calling the upload method transitions the machine to an uploading state, carries
+  out the operation, then returns to idle and fires a completion event. The event
+  payload separates newly created files from versioned ones, so the UI can show a
+  targeted confirmation — "2 files added" versus "1 file updated" — without parsing
+  the whole file list.
+*/
+
+cde.onUploadCompleted.add(({ created, versioned }) => {
+  log(`  [onUploadCompleted] created: ${created.length}, versioned: ${versioned.length}`);
+  for (const f of created) log(`    + ${f.name}`);
+  for (const f of versioned) log(`    ↑ ${f.name}`);
+});
+
+log("\n--- upload: create new files ---");
+const f1 = new File([new ArrayBuffer(100)], "column.ifc", { type: "application/octet-stream" });
+const f2 = new File([new ArrayBuffer(50)], "report.pdf");
+await cde.uploadFiles([f1, f2]);
+log(`  cde.files after upload: ${cde.files.length}`);
+
+/* MD
+  ### 🔄 Versioning an existing file
+  When the incoming file's base name and extension match an entry already in the list,
+  the upload method creates a new version rather than a duplicate. The file counter in
+  the version tag is computed from the existing version history, so the tag always
+  follows on from whatever the project already has.
+*/
+
+log("\n--- upload: version existing file ---");
+// "column.ifc" is already in cde.files from the previous upload.
+const f1v2 = new File([new ArrayBuffer(120)], "column.ifc", { type: "application/octet-stream" });
+await cde.uploadFiles([f1v2]);
+log(`  cde.files after version upload: ${cde.files.length}`);
+
+const colFile = cde.files.find(f => f.name === "column.ifc")!;
+log(`  column.ifc version tag: ${(colFile as any).versionTag}`);
+
+/* MD
+  ### 🏷️ Auto-metadata from a metadata group
+  When metadata grouping is active and a group is selected, every file uploaded in
+  that session inherits the group's metadata values automatically. The coordinator
+  selects the "Structural SD phase" group, drops files, and every new file arrives
+  already tagged — no post-upload editing required.
+*/
+
+log("\n--- upload: auto-metadata ---");
+cde.sendMachineEvent({ type: "SET_GROUPS_VIEW_MODE", mode: "metadata" });
+cde.selectedMetadataGroup = { discipline: "STR", phase: "SD" };
+
+const f3 = new File([new ArrayBuffer(80)], "foundations-v2.ifc", { type: "application/octet-stream" });
+await cde.uploadFiles([f3]);
+
+const uploaded = cde.files.find(f => f.name === "foundations-v2.ifc")!;
+log(`  discipline: ${uploaded.metadata.discipline}, phase: ${uploaded.metadata.phase}`);
+
+// Reset back to groups view for subsequent sections.
+cde.sendMachineEvent({ type: "SET_GROUPS_VIEW_MODE", mode: "groups" });
+cde.selectedMetadataGroup = null;
+
+/* MD
+  ### ⚠️ Recovering from an upload error
+  If the backend rejects the upload, the machine moves to an error state rather than
+  silently returning to idle. The error state carries the reason message so the UI can
+  surface it, and sending a dismiss event returns to idle so the user can try again.
+  No manual state cleanup is needed.
+*/
+
+log("\n--- upload: error recovery ---");
+cde.ctx = {
+  client: {
+    ...mockClient,
+    createFile: async () => { throw new Error("Upload failed — server unavailable"); },
+  } as any,
+  projectId: "mock",
+};
+
+const fBroken = new File([new ArrayBuffer(10)], "broken.ifc", { type: "application/octet-stream" });
+await cde.uploadFiles([fBroken]);
+
+if (cde.machineState.kind === "error") {
+  log(`  error reason: ${cde.machineState.reason}`);
+  cde.sendMachineEvent({ type: "DISMISS" });
+}
+log(`  state after dismiss: ${cde.machineState.kind}`);
+
+// Restore the working mock client.
+cde.ctx = { client: mockClient as any, projectId: "mock" };
+
+/* MD
+  ### 💾 File download cache
+  The download method on CDEManager keeps a buffer cache in memory so the viewer
+  does not re-fetch the same file version twice during a session. The cache logs each
+  access — a miss triggers a download, a hit returns the stored buffer immediately.
+  Only extensions in `cacheExtensions` are stored; all others are downloaded every
+  time so the cache stays focused on the large binary files that benefit most from it.
+
+  Note: files uploaded in the same session are already placed in the cache by the
+  upload method. The demo below uses a file injected directly — simulating a file
+  that arrived from a previous session load — to show a clean miss on the first
+  access.
+*/
+
+log("\n--- download cache ---");
+
+// A file loaded from the backend (not uploaded this session) starts with no cache entry.
+const serverFile = {
+  _id: "server-ifc", name: "arch.ifc", folderId: null, versionTag: "v3",
+  createdBy: "carol", createdAt: new Date(), metadata: {},
+} as CDEFile;
+cde.files = [...cde.files, serverFile];
+
+// First access — cache miss, buffer fetched and stored.
+const buf1 = await cde.downloadFile(serverFile);
+log(`  arch.ifc first access (miss): ${buf1.byteLength} bytes`);
+
+// Second access — cache hit, no network call.
+const buf2 = await cde.downloadFile(serverFile);
+log(`  arch.ifc second access (hit): ${buf2.byteLength} bytes`);
+
+// PDF extension is not in cacheExtensions — fetched but not stored.
+const pdfFile = cde.files.find(f => f.name === "report.pdf")!;
+const bufPdf = await cde.downloadFile(pdfFile);
+log(`  report.pdf access (skip): ${bufPdf.byteLength} bytes`);
+
+log(`\n  cacheExtensions: [${[...cde.cacheExtensions].join(", ")}]`);
+log(`  cacheMaxBytes: ${(cde.cacheMaxBytes / 1024 / 1024).toFixed(0)} MB`);