@thatopen/services 0.3.16 → 0.5.0

package/README.md

@@ -1,62 +1,62 @@
-# @thatopen/services
-
-Client library and CLI for building BIM apps and cloud components on [That Open Platform](https://platform.thatopen.com). Apps run inside the platform's browser environment; cloud components run server-side and can be triggered from any app.
-
-> **Using an AI assistant?** Point it at this single file and it can take you from nothing to a running app:
-> → [`docs/ai-quickstart.md`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/ai-quickstart.md)
-
-## Quick Start
-
-### 1. Install the CLI
-
-```bash
-npm install -g @thatopen/services@latest
-```
-
-### 2. Choose a project type
-
-| Type | Template | Use when |
-|------|----------|----------|
-| **App** | `app` | You're building a BIM app that runs in the platform's browser UI |
-| **Cloud component** | `cloud-component` | You're building server-side logic triggered by an app |
-
-### 3. Scaffold
-
-See the full command reference here:
-→ [`docs/cli/create.md`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/cli/create.md)
-
-To use beta engine libraries instead of the stable ones, see:
-→ [`docs/cli/swap.md`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/cli/swap.md)
-
-### 4. Next steps
-
-Once scaffolded, open `AGENTS.md` in the scaffolded project root — it has everything needed to start building.
-
-## Beta engine libraries (Founding Members)
-
-Founding Members get early access to the private beta engine libraries (`@thatopen-platform/*-beta`). The CLI configures access automatically — no npm account or manual token needed.
-
-```bash
-thatopen login --token <your-token>   # API token from the dashboard → Data → API Tokens
-thatopen create my-app --beta         # new project on the beta libraries
-# or, in an existing project:
-thatopen swap --beta                  # toggle the current project to beta
-```
-
-On `--beta`, the CLI fetches your read-only beta npm credentials and writes them to the project's `.npmrc`, so `npm install` resolves the private packages. The `.npmrc` is gitignored — it carries a credential, so don't commit or share it. Access is tied to your membership; non-Founding accounts get a clear message and the project is still created.
-
-## What's in this repository
-
-- **Library** — `EngineServicesClient` and `PlatformClient` for interacting with the That Open API (files, folders, apps, cloud components, executions, permissions).
-- **CLI** — `thatopen` command for scaffolding and publishing.
-- **Built-in component types** — TypeScript stubs for platform-hosted components.
-
-## Docs
-
-Full reference for all CLI commands and flags:
-→ [`docs/cli/paths.json`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/cli/paths.json)
-
-## Contributing
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, build commands, and publishing workflow.
-
+# @thatopen/services
+
+Client library and CLI for building BIM apps and cloud components on [That Open Platform](https://platform.thatopen.com). Apps run inside the platform's browser environment; cloud components run server-side and can be triggered from any app.
+
+> **Using an AI assistant?** Point it at this single file and it can take you from nothing to a running app:
+> → [`docs/ai-quickstart.md`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/ai-quickstart.md)
+
+## Quick Start
+
+### 1. Install the CLI
+
+```bash
+npm install -g @thatopen/services@latest
+```
+
+### 2. Choose a project type
+
+| Type | Template | Use when |
+|------|----------|----------|
+| **App** | `app` | You're building a BIM app that runs in the platform's browser UI |
+| **Cloud component** | `cloud-component` | You're building server-side logic triggered by an app |
+
+### 3. Scaffold
+
+See the full command reference here:
+→ [`docs/cli/create.md`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/cli/create.md)
+
+To use beta engine libraries instead of the stable ones, see:
+→ [`docs/cli/swap.md`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/cli/swap.md)
+
+### 4. Next steps
+
+Once scaffolded, open `AGENTS.md` in the scaffolded project root — it has everything needed to start building.
+
+## Beta engine libraries (Founding Members)
+
+Founding Members get early access to the private beta engine libraries (`@thatopen-platform/*-beta`). The CLI configures access automatically — no npm account or manual token needed.
+
+```bash
+thatopen login --token <your-token>   # API token from the dashboard → Data → API Tokens
+thatopen create my-app --beta         # new project on the beta libraries
+# or, in an existing project:
+thatopen swap --beta                  # toggle the current project to beta
+```
+
+On `--beta`, the CLI fetches your read-only beta npm credentials and writes them to the project's `.npmrc`, so `npm install` resolves the private packages. The `.npmrc` is gitignored — it carries a credential, so don't commit or share it. Access is tied to your membership; non-Founding accounts get a clear message and the project is still created.
+
+## What's in this repository
+
+- **Library** — `EngineServicesClient` and `PlatformClient` for interacting with the That Open API (files, folders, apps, cloud components, executions, permissions).
+- **CLI** — `thatopen` command for scaffolding and publishing.
+- **Built-in component types** — TypeScript stubs for platform-hosted components.
+
+## Docs
+
+Full reference for all CLI commands and flags:
+→ [`docs/cli/paths.json`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/cli/paths.json)
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, build commands, and publishing workflow.
+

package/dist/cli/commands/rhino.d.ts

@@ -0,0 +1,11 @@
+import { Command } from 'commander';
+
+/**
+ * `thatopen rhino ...` — installs the That Open Rhino plug-in.
+ *
+ * Deliberately much smaller than the Revit group. The Rhino plug-in's whole job in the
+ * interoperability layer is to PUBLISH what Rhino has; it applies nothing, so there is nothing to
+ * drive from here. Everything that turns a Rhino model into a change in somebody else's model lives
+ * in the platform, not in a plug-in.
+ */
+export declare const rhinoCommand: Command;

package/dist/cli/lib/plugin-install.d.ts

@@ -0,0 +1,24 @@
+import { EngineServicesClient } from '../../core/client';
+
+/**
+ * Downloads a private plug-in package and hands back the folder it unpacked into.
+ *
+ * npm does the work on purpose. It resolves what "latest" means, it authenticates against the
+ * restricted scope, and it verifies the tarball's integrity — three things this would otherwise
+ * hand-roll over HTTP and get subtly wrong. The only thing we add is the platform token, which
+ * `setupNpmrc` trades for registry credentials exactly as the `--beta` flows do. No npm account is
+ * involved and no npm token is ever asked for.
+ */
+export declare function fetchPluginPackage(client: EngineServicesClient, pkg: string, version?: string): Promise<{
+    dir: string;
+    cleanup: () => void;
+}>;
+/**
+ * Refuses to install while the host application is running.
+ *
+ * This is not caution, it is the difference between a failed install and a broken one. Both Revit
+ * and Rhino hold their plug-in assemblies open for the whole session, so a copy over a running host
+ * fails on the first locked file — AFTER copying the ones it reached. The result is a folder holding
+ * some new DLLs and some old, which loads, misbehaves, and looks like a bug in the product.
+ */
+export declare function assertHostClosed(processName: string, friendly: string): void;

package/dist/cli.js

@@ -6957,7 +6957,7 @@ class EngineServicesClient {
     return this.accessToken;
   }
   async #requestApi(method, path2, requestData) {
-    const { body, query, contentType, retries } = requestData || {};
+    const { body, query, contentType, retries, responseType } = requestData || {};
     const url2 = this.#buildUrl(path2);
     const cleanQuery = this.#cleanData(query);
     const token = await this.resolveAccessToken();
@@ -6986,6 +6986,9 @@ class EngineServicesClient {
           textResponse
         );
       }
+      if (responseType === "blob") {
+        return await response.blob();
+      }
       return response.json().then((data) => data).catch(() => void 0);
     } catch (e) {
       let retriesAmmount = retries != null ? retries : this.retries;
@@ -11683,6 +11686,60 @@ const swapCommand = new Command2("swap").description("Toggle between stable publ
     console.error("Failed to install dependencies. Run `npm install` manually.");
   }
 });
+async function fetchPluginPackage(client, pkg2, version = "latest") {
+  const work = require$$3.mkdtempSync(require$$2.join(node_os.tmpdir(), "thatopen-plugin-"));
+  const cleanup = () => {
+    try {
+      require$$3.rmSync(work, { recursive: true, force: true });
+    } catch {
+    }
+  };
+  try {
+    const creds = await setupNpmrc(client, work);
+    if (creds.status === "forbidden") {
+      throw new Error(
+        "Your account does not have access to the private plug-in packages. They need Founding access, the same as the beta engine libraries."
+      );
+    }
+    if (creds.status === "error") {
+      throw new Error(`Could not get registry credentials: ${creds.message}`);
+    }
+    require$$1.execFileSync("npm", ["pack", `${pkg2}@${version}`, "--silent"], {
+      cwd: work,
+      stdio: ["ignore", "ignore", "inherit"],
+      shell: process.platform === "win32"
+    });
+    const tgz = require$$3.readdirSync(work).find((f) => f.endsWith(".tgz"));
+    if (!tgz) throw new Error(`npm pack produced no tarball for ${pkg2}@${version}.`);
+    require$$1.execFileSync("tar", ["-xzf", tgz], { cwd: work, stdio: "inherit" });
+    const dir = require$$2.join(work, "package");
+    if (!require$$3.existsSync(dir)) throw new Error(`${tgz} did not unpack into a package/ folder.`);
+    return { dir, cleanup };
+  } catch (err) {
+    cleanup();
+    throw err;
+  }
+}
+function assertHostClosed(processName, friendly) {
+  let running = false;
+  try {
+    const out = require$$1.execFileSync(
+      "powershell",
+      ["-NoProfile", "-Command", `if (Get-Process -Name ${processName} -ErrorAction SilentlyContinue) { 'yes' }`],
+      { encoding: "utf-8" }
+    );
+    running = out.trim() === "yes";
+  } catch {
+    return;
+  }
+  if (running) {
+    throw new Error(
+      `${friendly} is running. Close it and run this again.
+
+Its plug-in files are locked while it is open, so installing now would replace some of them and not others.`
+    );
+  }
+}
 function discoveryFile() {
   const appData = process.env.APPDATA || require$$2.join(node_os.homedir(), "AppData", "Roaming");
   return require$$2.join(appData, "ThatOpen", "revit-addin.json");
@@ -11743,6 +11800,7 @@ async function configureAddin(apiUrl, accessToken) {
     key: accessToken
   });
 }
+const REVIT_ADDIN_PACKAGE = "@thatopen-platform/flow-revit";
 const revitCommand = new Command2("revit").description(
   "Revit collaboration — drive the That Open Revit add-in from the CLI"
 );
@@ -11826,6 +11884,70 @@ revitCommand.command("untake").description("Release a workset you own so teammat
   const r = await callAddin("untake", { workset: opts.workset });
   console.log(`Released workset "${r.released}".`);
 });
+revitCommand.command("install").alias("update").description("Install or update the That Open Revit add-in (Revit must be closed)").option("--version <version>", "A specific version instead of the latest", "latest").action(async (opts) => {
+  const cfg = requireResolvedConfig();
+  assertHostClosed("Revit", "Revit");
+  const client = new EngineServicesClient(cfg.accessToken, cfg.apiUrl);
+  console.log(`Fetching ${REVIT_ADDIN_PACKAGE}@${opts.version}...`);
+  const { dir, cleanup } = await fetchPluginPackage(
+    client,
+    REVIT_ADDIN_PACKAGE,
+    opts.version
+  );
+  try {
+    const installer = require$$2.join(dir, "install.ps1");
+    if (!require$$3.existsSync(installer)) {
+      throw new Error(`The package has no install.ps1. Got: ${require$$3.readdirSync(dir).join(", ")}`);
+    }
+    require$$1.execFileSync("powershell", ["-ExecutionPolicy", "Bypass", "-File", installer], {
+      stdio: "inherit"
+    });
+    console.log("\nStart Revit. The That Open tab will be there.");
+  } finally {
+    cleanup();
+  }
+});
+const RHINO_PLUGIN_PACKAGE = "@thatopen-platform/flow-rhino";
+const rhinoCommand = new Command2("rhino").description(
+  "Rhino interoperability — install the That Open Rhino plug-in"
+);
+rhinoCommand.command("install").alias("update").description("Install or update the That Open Rhino plug-in (Rhino must be closed)").option("--version <version>", "A specific version instead of the latest", "latest").action(async (opts) => {
+  const cfg = requireResolvedConfig();
+  assertHostClosed("Rhino", "Rhino");
+  const yak = findYak();
+  if (!yak) {
+    throw new Error(
+      "Could not find Yak.exe. It ships with Rhino, at C:\\Program Files\\Rhino 8\\System\\Yak.exe. Is Rhino 8 installed?"
+    );
+  }
+  const client = new EngineServicesClient(cfg.accessToken, cfg.apiUrl);
+  console.log(`Fetching ${RHINO_PLUGIN_PACKAGE}@${opts.version}...`);
+  const { dir, cleanup } = await fetchPluginPackage(client, RHINO_PLUGIN_PACKAGE, opts.version);
+  try {
+    const pkgDir = require$$2.join(dir, "pkg");
+    const yakFile = require$$3.existsSync(pkgDir) ? require$$3.readdirSync(pkgDir).find((f) => f.endsWith(".yak")) : void 0;
+    if (!yakFile) {
+      throw new Error(`The package has no .yak under pkg/. Got: ${require$$3.readdirSync(dir).join(", ")}`);
+    }
+    require$$1.execFileSync(yak, ["install", "--source", ".", "rhino-flow"], {
+      cwd: pkgDir,
+      stdio: "inherit"
+    });
+    console.log(`
+Installed ${yakFile}.`);
+    console.log("Start Rhino. The plug-in loads at startup, so its local server comes up with it.");
+  } finally {
+    cleanup();
+  }
+});
+function findYak() {
+  const candidates = [
+    "C:\\Program Files\\Rhino 8\\System\\Yak.exe",
+    "C:\\Program Files\\Rhino 9\\System\\Yak.exe",
+    "C:\\Program Files\\Rhino 8 WIP\\System\\Yak.exe"
+  ];
+  return candidates.find((p) => require$$3.existsSync(p));
+}
 const pkg = JSON.parse(
   require$$3.readFileSync(require$$2.join(__dirname, "..", "package.json"), "utf-8")
 );
@@ -11854,4 +11976,5 @@ program.addCommand(runCommand);
 program.addCommand(localServerCommand);
 program.addCommand(swapCommand);
 program.addCommand(revitCommand);
+program.addCommand(rhinoCommand);
 program.parse(process.argv);

package/dist/core/client.d.ts

@@ -219,6 +219,7 @@ export declare class EngineServicesClient {
         query?: object;
         contentType?: 'application/json' | 'multipart/form-data' | 'application/x-www-form-urlencoded';
         retries?: number;
+        responseType?: 'json' | 'blob';
     }): Promise<T>;
     /**
      * Lists all files accessible by the current token.

package/dist/core/platform-client.d.ts

@@ -86,6 +86,13 @@ export declare class PlatformClient extends EngineServicesClient {
      * User data is stripped of sensitive fields server-side.
      */
     getProjectData(projectId: string): Promise<ProjectData>;
+    /**
+     * Fetches a user's profile picture as raw image bytes, for showing member
+     * avatars inside an app. The route is bearer-authed, so it can't be used as
+     * an `<img src>` — turn the blob into an object URL with
+     * `URL.createObjectURL(blob)`. Rejects when the account has no avatar.
+     */
+    getAvatar(accountId: string): Promise<Blob>;
     /**
      * Checks whether the caller has a specific permission within a project.
      * Returns `{ hasPermission, scope }` where `scope` is `'global'` for