@thatopen/services 0.0.1

package/src/cli/templates/cloud-test/src/main.ts

@@ -0,0 +1,565 @@
+// Cloud Component — Platform API Test Suite
+// Tests all EngineServicesClient endpoints from a cloud component context.
+// Generated by: thatopen create --template cloud-test
+
+// Globals injected by the execution engine at runtime
+declare const thatOpenServices: import("thatopen-services").EngineServicesClient;
+declare const executionParams: Record<string, unknown>;
+declare const executionReporter: {
+  message(msg: string): void;
+  progress(pct: number): void;
+};
+declare const OBC: typeof import("@thatopen/components");
+declare const THREE: typeof import("three");
+declare const fs: typeof import("fs");
+
+type TestResult = {
+  name: string;
+  status: "pass" | "fail" | "skip";
+  message: string;
+};
+
+type TestGroup = {
+  name: string;
+  results: TestResult[];
+};
+
+async function runTest(
+  name: string,
+  fn: () => Promise<void>,
+): Promise<TestResult> {
+  try {
+    await fn();
+    return { name, status: "pass", message: "OK" };
+  } catch (err) {
+    return { name, status: "fail", message: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+function assert(condition: boolean, msg: string) {
+  if (!condition) throw new Error(msg);
+}
+
+export async function main() {
+  const groups: TestGroup[] = [];
+  const ts = Date.now();
+  let totalPass = 0;
+  let totalFail = 0;
+  let totalSkip = 0;
+  const groupNames = [
+    "Runtime Globals", "Folders", "Files", "Hidden Files", "Icons",
+    "General Item Operations", "Components", "Apps", "Execution", "Built-in Components",
+  ];
+
+  function report(group: TestGroup) {
+    groups.push(group);
+    for (const r of group.results) {
+      if (r.status === "pass") totalPass++;
+      else if (r.status === "fail") totalFail++;
+      else totalSkip++;
+    }
+    const summary = group.results
+      .map((r) => (r.status === "pass" ? "  \u2713 " : r.status === "fail" ? "  \u2717 " : "  \u25CB ") + r.name + ": " + r.message)
+      .join("\n");
+    executionReporter.message(group.name + "\n" + summary);
+    executionReporter.progress(Math.round((groups.length / groupNames.length) * 100));
+  }
+
+  executionReporter.message("Starting Platform API Test Suite...");
+
+  // ─── Runtime Globals ──────────────────────────────────────
+  const globalsResults: TestResult[] = [];
+  globalsResults.push(
+    await runTest("thatOpenServices exists", async () => {
+      assert(typeof thatOpenServices === "object", "Not an object");
+      assert(typeof thatOpenServices.listFiles === "function", "listFiles not a function");
+    }),
+  );
+  globalsResults.push(
+    await runTest("executionParams exists", async () => {
+      assert(typeof executionParams === "object", "Not an object");
+    }),
+  );
+  globalsResults.push(
+    await runTest("executionReporter exists", async () => {
+      assert(typeof executionReporter === "object", "Not an object");
+      assert(typeof executionReporter.message === "function", "message not a function");
+      assert(typeof executionReporter.progress === "function", "progress not a function");
+    }),
+  );
+  globalsResults.push(
+    await runTest("OBC exists", async () => {
+      assert(typeof OBC === "object", "Not an object");
+      assert(typeof OBC.Components === "function", "Components not a constructor");
+    }),
+  );
+  globalsResults.push(
+    await runTest("THREE exists", async () => {
+      assert(typeof THREE === "object", "Not an object");
+      assert(typeof THREE.Vector3 === "function", "Vector3 not a constructor");
+    }),
+  );
+  globalsResults.push(
+    await runTest("fs exists", async () => {
+      assert(typeof fs === "object", "Not an object");
+      assert(typeof fs.readFileSync === "function", "readFileSync not a function");
+    }),
+  );
+  report({ name: "Runtime Globals", results: globalsResults });
+
+  // ─── Folders ───────────────────────────────────────────────
+  const folderResults: TestResult[] = [];
+  let testFolderId = "";
+
+  folderResults.push(
+    await runTest("createFolder", async () => {
+      const folder = await thatOpenServices.createFolder("_cloud_test_folder_" + ts);
+      assert(!!folder._id, "_id missing");
+      assert(!!folder.name, "name missing");
+      testFolderId = folder._id;
+    }),
+  );
+  folderResults.push(
+    await runTest("getFolder", async () => {
+      assert(!!testFolderId, "No folder");
+      const folder = await thatOpenServices.getFolder(testFolderId);
+      assert(folder._id === testFolderId, "_id mismatch");
+    }),
+  );
+  folderResults.push(
+    await runTest("listFolders", async () => {
+      const folders = await thatOpenServices.listFolders();
+      assert(Array.isArray(folders), "Not an array");
+    }),
+  );
+  folderResults.push(
+    await runTest("updateFolder", async () => {
+      assert(!!testFolderId, "No folder");
+      const updated = await thatOpenServices.updateFolder(testFolderId, {
+        name: "_cloud_test_folder_renamed_" + ts,
+      });
+      assert(updated.name.includes("renamed"), "Name not updated");
+    }),
+  );
+  folderResults.push(
+    await runTest("archiveFolder", async () => {
+      assert(!!testFolderId, "No folder");
+      await thatOpenServices.archiveFolder(testFolderId);
+    }),
+  );
+  folderResults.push(
+    await runTest("recoverFolder", async () => {
+      assert(!!testFolderId, "No folder");
+      await thatOpenServices.recoverFolder(testFolderId);
+    }),
+  );
+  folderResults.push(
+    await runTest("downloadFolder", async () => {
+      assert(!!testFolderId, "No folder");
+      const response = await thatOpenServices.downloadFolder(testFolderId);
+      assert(!!response, "No response");
+    }),
+  );
+  report({ name: "Folders", results: folderResults });
+
+  // ─── Files ─────────────────────────────────────────────────
+  const fileResults: TestResult[] = [];
+  let testFileId = "";
+  const testContent = "cloud test file content " + ts;
+  const testBlob = new Blob([testContent], { type: "text/plain" });
+
+  fileResults.push(
+    await runTest("createFile", async () => {
+      const result = await thatOpenServices.createFile({
+        file: testBlob,
+        name: "_cloud_test_file_" + ts + ".txt",
+        versionTag: "v1",
+        parentFolderId: testFolderId || undefined,
+        metadata: { testKey: "testValue" },
+      });
+      assert(!!result.item._id, "item._id missing");
+      assert(!!result.version, "version missing");
+      testFileId = result.item._id;
+    }),
+  );
+  fileResults.push(
+    await runTest("getFile (with versions)", async () => {
+      assert(!!testFileId, "No file");
+      const file = await thatOpenServices.getFile(testFileId, { showVersions: true });
+      assert(file._id === testFileId, "_id mismatch");
+      assert(Array.isArray(file.versions), "versions not array");
+      assert(file.versions.length > 0, "versions empty");
+    }),
+  );
+  fileResults.push(
+    await runTest("listFiles", async () => {
+      const files = await thatOpenServices.listFiles();
+      assert(Array.isArray(files), "Not an array");
+    }),
+  );
+  fileResults.push(
+    await runTest("downloadFile", async () => {
+      assert(!!testFileId, "No file");
+      const response = await thatOpenServices.downloadFile(testFileId);
+      assert(response.ok !== false, "Response not ok");
+    }),
+  );
+  fileResults.push(
+    await runTest("getFileVersionMetadata", async () => {
+      assert(!!testFileId, "No file");
+      const metadata = await thatOpenServices.getFileVersionMetadata(
+        testFileId,
+        "v1",
+      );
+      assert(typeof metadata === "object", "metadata not object");
+    }),
+  );
+  fileResults.push(
+    await runTest("updateFileVersionMetadata", async () => {
+      assert(!!testFileId, "No file");
+      const result = await thatOpenServices.updateFileVersionMetadata(
+        testFileId,
+        "v1",
+        { discipline: "structural" },
+      );
+      assert(typeof result === "object", "result not object");
+    }),
+  );
+  fileResults.push(
+    await runTest("deleteFileVersionMetadata", async () => {
+      assert(!!testFileId, "No file");
+      await thatOpenServices.deleteFileVersionMetadata(testFileId, "v1");
+    }),
+  );
+  fileResults.push(
+    await runTest("updateFile (rename + new version)", async () => {
+      assert(!!testFileId, "No file");
+      const blob = new Blob(["updated content"], { type: "text/plain" });
+      const result = await thatOpenServices.updateFile(testFileId, {
+        name: "_cloud_test_file_renamed_" + ts + ".txt",
+        file: blob,
+        versionTag: "v2",
+      });
+      assert(!!result.version || !!result.item, "No update result");
+    }),
+  );
+  fileResults.push(
+    await runTest("archiveFile", async () => {
+      assert(!!testFileId, "No file");
+      await thatOpenServices.archiveFile(testFileId);
+    }),
+  );
+  fileResults.push(
+    await runTest("recoverFile", async () => {
+      assert(!!testFileId, "No file");
+      await thatOpenServices.recoverFile(testFileId);
+    }),
+  );
+  report({ name: "Files", results: fileResults });
+
+  // ─── Hidden Files ──────────────────────────────────────────
+  const hiddenResults: TestResult[] = [];
+  let testHiddenId = "";
+
+  hiddenResults.push(
+    await runTest("createHiddenFile", async () => {
+      assert(!!testFileId, "No parent file");
+      const blob = new Blob(["hidden content"], { type: "text/plain" });
+      const result = await thatOpenServices.createHiddenFile(blob, testFileId);
+      assert(!!result.hiddenFileId, "hiddenFileId missing");
+      testHiddenId = result.hiddenFileId;
+    }),
+  );
+  hiddenResults.push(
+    await runTest("getHiddenFile", async () => {
+      assert(!!testHiddenId, "No hidden file");
+      const hidden = await thatOpenServices.getHiddenFile(testHiddenId);
+      assert(!!hidden._id, "_id missing");
+    }),
+  );
+  hiddenResults.push(
+    await runTest("getHiddenFilesByParent", async () => {
+      assert(!!testFileId, "No parent file");
+      const files = await thatOpenServices.getHiddenFilesByParent(testFileId);
+      assert(Array.isArray(files), "Not an array");
+      assert(files.length > 0, "No hidden files found");
+    }),
+  );
+  hiddenResults.push(
+    await runTest("downloadHiddenFile", async () => {
+      assert(!!testHiddenId, "No hidden file");
+      const response = await thatOpenServices.downloadHiddenFile(testHiddenId);
+      assert(!!response, "No response");
+    }),
+  );
+  hiddenResults.push(
+    await runTest("deleteHiddenFile", async () => {
+      assert(!!testHiddenId, "No hidden file");
+      await thatOpenServices.deleteHiddenFile(testHiddenId);
+    }),
+  );
+  hiddenResults.push(
+    await runTest("deleteHiddenFilesByParent", async () => {
+      assert(!!testFileId, "No parent file");
+      const blob = new Blob(["temp hidden"], { type: "text/plain" });
+      await thatOpenServices.createHiddenFile(blob, testFileId);
+      const result = await thatOpenServices.deleteHiddenFilesByParent(testFileId);
+      assert(Array.isArray(result), "Not an array");
+    }),
+  );
+  report({ name: "Hidden Files", results: hiddenResults });
+
+  // ─── Icons ─────────────────────────────────────────────────
+  const iconResults: TestResult[] = [];
+  // 1x1 transparent PNG
+  const pngBytes = new Uint8Array([
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00,
+    0x0d, 0x49, 0x48, 0x44, 0x52, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00,
+    0x00, 0x01, 0x08, 0x02, 0x00, 0x00, 0x00, 0x90, 0x77, 0x53, 0xde,
+    0x00, 0x00, 0x00, 0x0c, 0x49, 0x44, 0x41, 0x54, 0x08, 0xd7, 0x63,
+    0xf8, 0xcf, 0xc0, 0x00, 0x00, 0x00, 0x02, 0x00, 0x01, 0xe2, 0x21,
+    0xbc, 0x33, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae,
+    0x42, 0x60, 0x82,
+  ]);
+  const iconBlob = new Blob([pngBytes], { type: "image/png" });
+
+  iconResults.push(
+    await runTest("uploadItemIcon", async () => {
+      assert(!!testFileId, "No item");
+      await thatOpenServices.uploadItemIcon(testFileId, iconBlob);
+    }),
+  );
+  iconResults.push(
+    await runTest("getItemIcon", async () => {
+      assert(!!testFileId, "No item");
+      const response = await thatOpenServices.getItemIcon(testFileId);
+      assert(!!response, "No response");
+    }),
+  );
+  iconResults.push(
+    await runTest("removeItemIcon", async () => {
+      assert(!!testFileId, "No item");
+      await thatOpenServices.removeItemIcon(testFileId);
+    }),
+  );
+  report({ name: "Icons", results: iconResults });
+
+  // ─── General Item Operations ───────────────────────────────
+  const generalResults: TestResult[] = [];
+
+  generalResults.push(
+    await runTest("updateItem (rename without version)", async () => {
+      assert(!!testFileId, "No item");
+      const item = await thatOpenServices.updateItem(testFileId, {
+        name: "_cloud_test_file_general_" + ts + ".txt",
+      });
+      assert(!!item._id, "item._id missing");
+    }),
+  );
+  generalResults.push(
+    await runTest("createVersion", async () => {
+      assert(!!testFileId, "No item");
+      const blob = new Blob(["version 3 content"], { type: "text/plain" });
+      const version = await thatOpenServices.createVersion(testFileId, blob, "v3");
+      assert(!!version, "version missing");
+    }),
+  );
+  report({ name: "General Item Operations", results: generalResults });
+
+  // Cleanup test file
+  if (testFileId) {
+    try { await thatOpenServices.archiveFile(testFileId); } catch { /* cleanup */ }
+  }
+
+  // ─── Components ────────────────────────────────────────────
+  const compResults: TestResult[] = [];
+  let testComponentId = "";
+
+  compResults.push(
+    await runTest("createComponent", async () => {
+      const blob = new Blob(["// test component"], { type: "application/javascript" });
+      const result = await thatOpenServices.createComponent({
+        file: blob,
+        name: "_cloud_test_component_" + ts,
+        versionTag: "v1",
+        componentProps: { type: "CLOUD", tier: "FREE" },
+      });
+      assert(!!result.item._id, "item._id missing");
+      assert(!!result.version, "version missing");
+      testComponentId = result.item._id;
+    }),
+  );
+  compResults.push(
+    await runTest("getComponent (with versions)", async () => {
+      assert(!!testComponentId, "No component");
+      const comp = await thatOpenServices.getComponent(testComponentId, { showVersions: true });
+      assert(comp._id === testComponentId, "_id mismatch");
+      assert(Array.isArray(comp.versions), "versions not array");
+    }),
+  );
+  compResults.push(
+    await runTest("listComponents", async () => {
+      const components = await thatOpenServices.listComponents();
+      assert(Array.isArray(components), "Not an array");
+    }),
+  );
+  compResults.push(
+    await runTest("updateComponent", async () => {
+      assert(!!testComponentId, "No component");
+      const blob = new Blob(["// updated"], { type: "application/javascript" });
+      const result = await thatOpenServices.updateComponent(testComponentId, {
+        name: "_cloud_test_component_renamed_" + ts,
+        file: blob,
+        versionTag: "v2",
+        componentProps: { type: "CLOUD", tier: "FREE" },
+      });
+      assert(!!result.version || !!result.item, "No update result");
+    }),
+  );
+  compResults.push(
+    await runTest("downloadComponent", async () => {
+      assert(!!testComponentId, "No component");
+      const response = await thatOpenServices.downloadComponent(testComponentId);
+      assert(!!response, "No response");
+    }),
+  );
+  compResults.push(
+    await runTest("downloadComponentBundle", async () => {
+      assert(!!testComponentId, "No component");
+      const response = await thatOpenServices.downloadComponentBundle(testComponentId);
+      assert(!!response, "No response");
+    }),
+  );
+  compResults.push(
+    await runTest("archiveComponent", async () => {
+      assert(!!testComponentId, "No component");
+      await thatOpenServices.archiveComponent(testComponentId);
+    }),
+  );
+  compResults.push(
+    await runTest("recoverComponent", async () => {
+      assert(!!testComponentId, "No component");
+      await thatOpenServices.recoverComponent(testComponentId);
+    }),
+  );
+  report({ name: "Components", results: compResults });
+
+  // ─── Apps ───────────────────────────────────────────────────
+  const appResults: TestResult[] = [];
+  let testAppId = "";
+
+  appResults.push(
+    await runTest("listApps", async () => {
+      const apps = await thatOpenServices.listApps();
+      assert(Array.isArray(apps), "Not an array");
+    }),
+  );
+  appResults.push(
+    await runTest("createApp", async () => {
+      const blob = new Blob(["// test app"], { type: "application/javascript" });
+      const result = await thatOpenServices.createApp({
+        file: blob,
+        name: "_cloud_test_app_" + ts,
+        versionTag: "v1",
+      });
+      assert(!!result.item._id, "item._id missing");
+      assert(!!result.version, "version missing");
+      testAppId = result.item._id;
+    }),
+  );
+  appResults.push(
+    await runTest("downloadApp", async () => {
+      assert(!!testAppId, "No app");
+      const response = await thatOpenServices.downloadApp(testAppId);
+      assert(!!response, "No response");
+    }),
+  );
+  appResults.push(
+    await runTest("downloadAppBundle", async () => {
+      assert(!!testAppId, "No app");
+      const response = await thatOpenServices.downloadAppBundle(testAppId);
+      assert(!!response, "No response");
+    }),
+  );
+  appResults.push(
+    await runTest("archiveApp", async () => {
+      assert(!!testAppId, "No app");
+      await thatOpenServices.archiveApp(testAppId);
+    }),
+  );
+  report({ name: "Apps", results: appResults });
+
+  // ─── Execution ─────────────────────────────────────────────
+  // Uses the test component created above to exercise execution endpoints.
+  // Note: executeComponent triggers a NEW execution of the given component.
+  // The component bundle is not valid, so the execution itself will likely
+  // fail, but the API calls are still fully tested.
+  const execResults: TestResult[] = [];
+  let testExecId = "";
+
+  if (testComponentId) {
+    execResults.push(
+      await runTest("executeComponent", async () => {
+        const result = await thatOpenServices.executeComponent(testComponentId, {
+          testParam: "hello",
+        });
+        assert(!!result.executionId, "executionId missing");
+        testExecId = result.executionId;
+      }),
+    );
+    execResults.push(
+      await runTest("getExecution", async () => {
+        assert(!!testExecId, "No execution");
+        const execution = await thatOpenServices.getExecution(testExecId);
+        assert(!!execution, "execution missing");
+      }),
+    );
+    execResults.push(
+      await runTest("listExecutions", async () => {
+        assert(!!testComponentId, "No component");
+        const executions = await thatOpenServices.listExecutions(testComponentId);
+        assert(Array.isArray(executions), "Not an array");
+      }),
+    );
+  } else {
+    const skip = (n: string) => ({ name: n, status: "skip" as const, message: "Component creation failed" });
+    execResults.push(skip("executeComponent"), skip("getExecution"), skip("listExecutions"));
+  }
+  report({ name: "Execution", results: execResults });
+
+  // ─── Built-in Components ───────────────────────────────────
+  const builtInResults: TestResult[] = [];
+  builtInResults.push(
+    await runTest("getBuiltInComponent (HelloWorld)", async () => {
+      const source = await thatOpenServices.getBuiltInComponent(
+        "2c4ae432-fc24-43e9-9783-0c960c674e96",
+      );
+      assert(typeof source === "string", "Not a string");
+      assert(source.length > 0, "Empty source");
+    }),
+  );
+  report({ name: "Built-in Components", results: builtInResults });
+
+  // ─── Cleanup ───────────────────────────────────────────────
+  if (testComponentId) {
+    try { await thatOpenServices.archiveComponent(testComponentId); } catch { /* cleanup */ }
+  }
+  if (testFolderId) {
+    try { await thatOpenServices.archiveFolder(testFolderId); } catch { /* cleanup */ }
+  }
+
+  // ─── Summary ───────────────────────────────────────────────
+  const summary = totalPass + " passed, " + totalFail + " failed, " + totalSkip + " skipped";
+  executionReporter.message("\nTest suite complete: " + summary);
+  executionReporter.progress(100);
+
+  if (totalFail > 0) {
+    const failedNames = groups
+      .flatMap((g) => g.results)
+      .filter((r) => r.status === "fail")
+      .map((r) => r.name + ": " + r.message)
+      .join("; ");
+    return { type: "WARNING", message: summary + " — Failed: " + failedNames };
+  }
+  return { type: "SUCCESS", message: summary };
+}

package/src/cli/templates/default/CONTEXT.md

@@ -0,0 +1,92 @@
+# ThatOpen App
+
+This is an app built for the That Open Platform.
+It runs in the browser inside the platform's iframe.
+
+## How this app works
+
+- **Entry point**: `src/main.ts` — runs as an IIFE when the platform loads the app.
+- **Build output**: `dist/bundle.js` — a single IIFE file built by Vite.
+- **Platform context**: The platform injects `window.__THATOPEN_CONTEXT__` with:
+  - `appId` — this app's unique ID
+  - `projectId` — the project this app belongs to
+  - `accessToken` — Auth0 JWT for API calls
+  - `apiUrl` — base URL for the That Open API
+- **Mount point**: Your app renders into the `#that-open-app` element in `index.html`.
+
+## Commands
+
+```bash
+npm run dev        # Start dev server (esbuild watch + serve on :4000)
+npm run build               # Build dist/bundle.js (Vite/Rollup production build)
+npm run login               # Authenticate with the platform (saves token locally)
+npm run publish             # Publish to the platform
+```
+
+### Local development
+
+Apps run inside the That Open Platform (platform.thatopen.com) within a project —
+not as standalone websites. To develop locally:
+
+1. Run `npm run dev` — this watches source files with esbuild and serves the bundle on port 4000.
+2. Open your project on the platform and click the debug button.
+3. Live reload is enabled — save a file to rebuild automatically.
+
+The dev server (`thatopen serve`) uses esbuild for near-instant incremental rebuilds.
+**Important**: Do NOT run `vite`, `vite build --watch`, or `npx vite` directly for development.
+Always use `npm run dev` which runs `thatopen serve` under the hood.
+
+## Adding BIM capabilities
+
+To add 3D BIM viewing, install the BIM dependencies:
+
+```bash
+npm install @thatopen/components @thatopen/ui three thatopen-services
+```
+
+Then follow the BIM app pattern:
+
+```ts
+import * as THREE from "three";
+import * as OBC from "@thatopen/components";
+import * as OBF from "@thatopen/components-front";
+import * as FRAGS from "@thatopen/fragments";
+import * as BUI from "@thatopen/ui";
+import * as CUI from "@thatopen/ui-obc";
+import { PlatformClient, AppManager, ViewportManager } from "thatopen-services";
+
+const client = PlatformClient.fromPlatformContext();
+const { components } = await client.setup(
+  { OBC, OBF, BUI, CUI, THREE, FRAGS },
+  AppManager, ViewportManager,
+);
+
+const viewports = components.get(ViewportManager);
+const { element, world } = await viewports.create();
+```
+
+## EngineServicesClient API
+
+If you install `thatopen-services`, you can make API calls:
+
+```ts
+import { PlatformClient } from "thatopen-services";
+
+const client = PlatformClient.fromPlatformContext();
+
+// Files
+const files = await client.listFiles();
+const response = await client.downloadFile(fileId);
+
+// Folders
+const folders = await client.listFolders();
+await client.createFolder("My Folder");
+
+// Execute cloud components
+const { executionId } = await client.executeComponent(componentId, { param: "value" });
+```
+
+## Configuration
+
+- `.thatopen` — local config (gitignored). Created by `npm run login`. Contains `accessToken`, `apiUrl`, and `appId` after first publish.
+- `vite.config.js` — builds to IIFE format as `dist/bundle.js`. All dependencies are bundled.

package/src/cli/templates/default/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "thatopen serve",
+    "build": "vite build",
+    "login": "thatopen login --local",
+    "publish": "thatopen publish"
+  },
+  "devDependencies": {
+    "typescript": "^5.2.0",
+    "vite": "^5.2.0"
+  }
+}