@thatopen/services 0.3.16 → 0.4.0

package/dist/vite-env.d.ts

@@ -1 +1 @@
-/// <reference types="vite/client" />
+/// <reference types="vite/client" />

package/docs/ai-quickstart.md

@@ -1,130 +1,130 @@
-# That Open Platform — AI Quick Start (zero to a running app or cloud component)
-
-You are an AI assistant. A user pointed you at this URL so you can scaffold and run something
-on the [That Open Platform](https://platform.thatopen.com) from scratch, using
-`@thatopen/services` (the `thatopen` CLI + client library). Follow the steps below in order.
-
-> The only secret you need is a **platform API token** — **not** an npm token. The CLI
-> derives private beta-registry access from the platform token automatically.
-
----
-
-## First — what are you building? (ask if the user hasn't said)
-
-There are two kinds of project. **If the user hasn't told you which they want, ASK them
-before scaffolding** — explain it in plain terms and let them pick:
-
-- **App** — something people *open and click around in*, running in the platform's browser
-  UI: a 3D BIM viewer, a dashboard, a form, a custom tool. Choose this when the goal is a
-  visual interface. Template: `app`.
-- **Cloud component** — *server-side logic* with no UI of its own, running in the platform's
-  cloud and triggered by an app or an automation to do work on the project's data — e.g.
-  convert a file (IFC→fragments, point cloud→tiles), generate a report, run a calculation.
-  Choose this when the goal is processing/automation, not a screen. Template: `cloud-component`.
-
-Steps 0–2 are identical for both; they diverge only at `create` (step 3) and how you run them
-(step 4). This guide marks **[app]** / **[component]** where they differ.
-
-## 0. Prerequisites (check, don't assume)
-
-- **Node.js ≥ 18** and **npm** — verify with `node -v`.
-- A **That Open Platform API token**. The user creates it themselves:
-  → **https://platform.thatopen.com/dashboard/data → API Tokens → create → copy.**
-  Ask the user to paste it. **Never print it back, never write it into a file, never commit it.**
-
-## 1. Install the CLI
-
-```bash
-npm install -g @thatopen/services@latest
-```
-
-## 2. Log in (do this BEFORE creating the project)
-
-Get the token from the platform dashboard — **https://platform.thatopen.com/dashboard/data**
-→ **API Tokens** → create → copy. Ask the user to paste it, then run:
-
-```bash
-thatopen login --token <platform-token>
-```
-
-This validates the token and stores it in `~/.thatopen/config.json`. Login **must** come
-first: the next step's install pulls the private `@thatopen-platform/*-beta` packages, and
-`create` uses your logged-in token to write an authenticated `.npmrc` so that install can
-resolve them. No npm account or manual npm token is involved.
-
-## 3. Scaffold a beta project
-
-**[app]**
-```bash
-thatopen create my-app --beta
-cd my-app
-```
-
-**[component]**
-```bash
-thatopen create my-component -t cloud-component --beta
-cd my-component
-```
-
-`--beta` is required for now (the templates use engine APIs that currently live only in the
-beta libraries; public support lands with the October release). `create` configures private
-beta access from your platform token and runs `npm install` for you. The **app** scaffold is
-a complete working viewer; the **cloud-component** scaffold is a `main()` entry point plus a
-`declarations.json` (the parameters the component accepts) — read its `README.md`, which
-explains the exactly-four globals the cloud engine injects (do NOT import them) and how to
-read/write the project's data.
-
-## 4. Run it
-
-**[app]**
-```bash
-npm run dev
-```
-Serves the app and opens it inside the platform. **You now have a complete, working viewer** —
-model loading, spatial tree, properties, measurement, sectioning, and more.
-
-**[component]**
-```bash
-npm run run        # executes the component locally against the platform (no browser)
-```
-Runs `main()` in a local emulation of the cloud engine so you can iterate before publishing.
-
-## 5. Then build — read the in-project agent guide
-
-The scaffold is real, working code — a complete viewer **[app]** or a runnable `main()`
-**[component]** — not a blank page. **Before changing anything**, open and follow:
-
-```
-node_modules/@thatopen/services/resources/AGENTS.md
-```
-
-(The scaffolded project's own `AGENTS.md` points here too.) It is the canonical guide for
-**both** project types: it indexes every platform built-in, the client API, the CLI, and the
-engine / UI example sets. Load those indexes before writing code. For an **app**, **all UI
-must be built with Lit + `@thatopen/ui` (`BUI`)** — consult the design system first. Run the
-scaffold first, then extend it; don't rebuild from scratch.
-
-## 6. Publish (when ready)
-
-```bash
-npm run publish
-```
-
-Builds, zips (`dist/bundle.zip`), and uploads a new version to the platform — for an **app**
-or a **component** (a component also ships its `declarations.json`). Re-run it any time to
-push a new version.
-
-Once published, it shows up at **https://platform.thatopen.com/dashboard/data** — an **app**
-under **Apps**, a **cloud component** under **Components**. Either way it isn't running
-anywhere yet: to actually use it, **add it to one of your projects** from there. (A cloud
-component, once added to a project, is then triggered by an app or an automation in it.)
-
----
-
-## Rules for you, the assistant
-
-- **Platform token only.** Never introduce, request, or store an npm token.
-- **Never echo or persist the user's token.** It belongs only in `~/.thatopen/config.json` /
-  `.npmrc`, both of which the CLI manages and git-ignores.
-- **Propose a short plan and get the user's OK** before changing files.
-- The scaffold already works — **extend it, don't replace it.**
+# That Open Platform — AI Quick Start (zero to a running app or cloud component)
+
+You are an AI assistant. A user pointed you at this URL so you can scaffold and run something
+on the [That Open Platform](https://platform.thatopen.com) from scratch, using
+`@thatopen/services` (the `thatopen` CLI + client library). Follow the steps below in order.
+
+> The only secret you need is a **platform API token** — **not** an npm token. The CLI
+> derives private beta-registry access from the platform token automatically.
+
+---
+
+## First — what are you building? (ask if the user hasn't said)
+
+There are two kinds of project. **If the user hasn't told you which they want, ASK them
+before scaffolding** — explain it in plain terms and let them pick:
+
+- **App** — something people *open and click around in*, running in the platform's browser
+  UI: a 3D BIM viewer, a dashboard, a form, a custom tool. Choose this when the goal is a
+  visual interface. Template: `app`.
+- **Cloud component** — *server-side logic* with no UI of its own, running in the platform's
+  cloud and triggered by an app or an automation to do work on the project's data — e.g.
+  convert a file (IFC→fragments, point cloud→tiles), generate a report, run a calculation.
+  Choose this when the goal is processing/automation, not a screen. Template: `cloud-component`.
+
+Steps 0–2 are identical for both; they diverge only at `create` (step 3) and how you run them
+(step 4). This guide marks **[app]** / **[component]** where they differ.
+
+## 0. Prerequisites (check, don't assume)
+
+- **Node.js ≥ 18** and **npm** — verify with `node -v`.
+- A **That Open Platform API token**. The user creates it themselves:
+  → **https://platform.thatopen.com/dashboard/data → API Tokens → create → copy.**
+  Ask the user to paste it. **Never print it back, never write it into a file, never commit it.**
+
+## 1. Install the CLI
+
+```bash
+npm install -g @thatopen/services@latest
+```
+
+## 2. Log in (do this BEFORE creating the project)
+
+Get the token from the platform dashboard — **https://platform.thatopen.com/dashboard/data**
+→ **API Tokens** → create → copy. Ask the user to paste it, then run:
+
+```bash
+thatopen login --token <platform-token>
+```
+
+This validates the token and stores it in `~/.thatopen/config.json`. Login **must** come
+first: the next step's install pulls the private `@thatopen-platform/*-beta` packages, and
+`create` uses your logged-in token to write an authenticated `.npmrc` so that install can
+resolve them. No npm account or manual npm token is involved.
+
+## 3. Scaffold a beta project
+
+**[app]**
+```bash
+thatopen create my-app --beta
+cd my-app
+```
+
+**[component]**
+```bash
+thatopen create my-component -t cloud-component --beta
+cd my-component
+```
+
+`--beta` is required for now (the templates use engine APIs that currently live only in the
+beta libraries; public support lands with the October release). `create` configures private
+beta access from your platform token and runs `npm install` for you. The **app** scaffold is
+a complete working viewer; the **cloud-component** scaffold is a `main()` entry point plus a
+`declarations.json` (the parameters the component accepts) — read its `README.md`, which
+explains the exactly-four globals the cloud engine injects (do NOT import them) and how to
+read/write the project's data.
+
+## 4. Run it
+
+**[app]**
+```bash
+npm run dev
+```
+Serves the app and opens it inside the platform. **You now have a complete, working viewer** —
+model loading, spatial tree, properties, measurement, sectioning, and more.
+
+**[component]**
+```bash
+npm run run        # executes the component locally against the platform (no browser)
+```
+Runs `main()` in a local emulation of the cloud engine so you can iterate before publishing.
+
+## 5. Then build — read the in-project agent guide
+
+The scaffold is real, working code — a complete viewer **[app]** or a runnable `main()`
+**[component]** — not a blank page. **Before changing anything**, open and follow:
+
+```
+node_modules/@thatopen/services/resources/AGENTS.md
+```
+
+(The scaffolded project's own `AGENTS.md` points here too.) It is the canonical guide for
+**both** project types: it indexes every platform built-in, the client API, the CLI, and the
+engine / UI example sets. Load those indexes before writing code. For an **app**, **all UI
+must be built with Lit + `@thatopen/ui` (`BUI`)** — consult the design system first. Run the
+scaffold first, then extend it; don't rebuild from scratch.
+
+## 6. Publish (when ready)
+
+```bash
+npm run publish
+```
+
+Builds, zips (`dist/bundle.zip`), and uploads a new version to the platform — for an **app**
+or a **component** (a component also ships its `declarations.json`). Re-run it any time to
+push a new version.
+
+Once published, it shows up at **https://platform.thatopen.com/dashboard/data** — an **app**
+under **Apps**, a **cloud component** under **Components**. Either way it isn't running
+anywhere yet: to actually use it, **add it to one of your projects** from there. (A cloud
+component, once added to a project, is then triggered by an app or an automation in it.)
+
+---
+
+## Rules for you, the assistant
+
+- **Platform token only.** Never introduce, request, or store an npm token.
+- **Never echo or persist the user's token.** It belongs only in `~/.thatopen/config.json` /
+  `.npmrc`, both of which the CLI manages and git-ignores.
+- **Propose a short plan and get the user's OK** before changing files.
+- The scaffold already works — **extend it, don't replace it.**

package/docs/cli/create.md

@@ -1,29 +1,29 @@
----
-description: "Scaffold a new app or cloud component project from a template. Covers --template (app for browser BIM apps, cloud-component for server-side components), --beta for switching to private beta engine libraries at scaffold time, and using '.' as the project name to scaffold into the current directory."
----
-
-## thatopen create
-
-Scaffolds a new ThatOpen project and runs `npm install` automatically.
-
-**Usage:**
-```bash
-thatopen create <project-name> [flags]
-thatopen create .             # scaffold into the current directory
-```
-
-**Flags:**
-
-- `--template <template>`, `-t` — Template to use. Default: `app`.
-  - `app` — Browser BIM app running inside the platform iframe.
-  - `cloud-component` — Server-side component executed by the platform's cloud engine and consumed in apps and/or automations.
-- `--beta` — Use private beta engine libraries (`@thatopen-platform/*-beta`) instead of the public ones. Sets `beta: true` in `.thatopen` so `serve`, `local-server`, and `vite build` all resolve to beta packages automatically. Requires beta npm access configured (handled automatically once you `thatopen login`).
-
-> **`--beta` is currently required.** The templates depend on engine APIs that only exist in the beta libraries, so scaffolding without `--beta` errors out for now. Public (non-beta) support is coming with the October release.
-
-**Examples:**
-```bash
-thatopen create my-app --beta
-thatopen create my-app -t cloud-component --beta
-thatopen create . --beta
-```
+---
+description: "Scaffold a new app or cloud component project from a template. Covers --template (app for browser BIM apps, cloud-component for server-side components), --beta for switching to private beta engine libraries at scaffold time, and using '.' as the project name to scaffold into the current directory."
+---
+
+## thatopen create
+
+Scaffolds a new ThatOpen project and runs `npm install` automatically.
+
+**Usage:**
+```bash
+thatopen create <project-name> [flags]
+thatopen create .             # scaffold into the current directory
+```
+
+**Flags:**
+
+- `--template <template>`, `-t` — Template to use. Default: `app`.
+  - `app` — Browser BIM app running inside the platform iframe.
+  - `cloud-component` — Server-side component executed by the platform's cloud engine and consumed in apps and/or automations.
+- `--beta` — Use private beta engine libraries (`@thatopen-platform/*-beta`) instead of the public ones. Sets `beta: true` in `.thatopen` so `serve`, `local-server`, and `vite build` all resolve to beta packages automatically. Requires beta npm access configured (handled automatically once you `thatopen login`).
+
+> **`--beta` is currently required.** The templates depend on engine APIs that only exist in the beta libraries, so scaffolding without `--beta` errors out for now. Public (non-beta) support is coming with the October release.
+
+**Examples:**
+```bash
+thatopen create my-app --beta
+thatopen create my-app -t cloud-component --beta
+thatopen create . --beta
+```

package/docs/cli/local-server.md

@@ -1,38 +1,38 @@
----
-description: "Start a local HTTP + Socket.IO server that replicates the platform's cloud execution API on port 4001, with esbuild watch mode. Connect an app to it via EngineServicesClient's localServerUrl option to execute and monitor a local cloud component without publishing."
----
-
-## thatopen local-server
-
-Starts a local server that mimics the platform's cloud execution API. Runs esbuild in watch mode and rebuilds the component on every save.
-
-Connect an app to it by passing `localServerUrl` to `EngineServicesClient`:
-
-```ts
-const client = new EngineServicesClient(token, apiUrl, {
-  localServerUrl: 'http://localhost:4001'
-});
-```
-
-**Usage:**
-```bash
-thatopen local-server [flags]
-```
-
-**Flags:**
-
-- `--port <port>` — Port to run the server on. Default: `4001`.
-- `--skip-build` — Skip the initial build and use the existing `dist/bundle.js`.
-
-**Endpoints:**
-
-- `POST /api/processor/:componentId/execute`
-- `GET  /api/processor/progress/:executionId`
-- `POST /api/processor/progress/:executionId/abort`
-- `GET  /api/processor/:componentId/progress`
-
-**Example:**
-```bash
-thatopen local-server
-thatopen local-server --port 5000
-```
+---
+description: "Start a local HTTP + Socket.IO server that replicates the platform's cloud execution API on port 4001, with esbuild watch mode. Connect an app to it via EngineServicesClient's localServerUrl option to execute and monitor a local cloud component without publishing."
+---
+
+## thatopen local-server
+
+Starts a local server that mimics the platform's cloud execution API. Runs esbuild in watch mode and rebuilds the component on every save.
+
+Connect an app to it by passing `localServerUrl` to `EngineServicesClient`:
+
+```ts
+const client = new EngineServicesClient(token, apiUrl, {
+  localServerUrl: 'http://localhost:4001'
+});
+```
+
+**Usage:**
+```bash
+thatopen local-server [flags]
+```
+
+**Flags:**
+
+- `--port <port>` — Port to run the server on. Default: `4001`.
+- `--skip-build` — Skip the initial build and use the existing `dist/bundle.js`.
+
+**Endpoints:**
+
+- `POST /api/processor/:componentId/execute`
+- `GET  /api/processor/progress/:executionId`
+- `POST /api/processor/progress/:executionId/abort`
+- `GET  /api/processor/:componentId/progress`
+
+**Example:**
+```bash
+thatopen local-server
+thatopen local-server --port 5000
+```

package/docs/cli/login.md

@@ -1,32 +1,32 @@
----
-description: "Authenticate with the ThatOpen platform by validating an access token against the API. Saves credentials globally (~/.thatopen/config.json) by default, or locally to the project's .thatopen file with --local. Local config takes priority over global."
----
-
-## thatopen login
-
-Validates an access token against the platform API and saves the credentials. Run this once globally before using any other command, or per-project with `--local`.
-
-To get a token:
-1. Go to [https://platform.thatopen.com](https://platform.thatopen.com)
-2. In the header, click **Data**
-3. Find the **Tokens** card and create a new token
-4. Enable the permissions: **Apps**, **Components**, and **Storage**
-5. Copy the token
-
-**Usage:**
-```bash
-thatopen login --token <token> [flags]
-```
-
-**Flags:**
-
-- `--token <token>` — Access token from the dashboard. Required.
-- `--api-url <url>` — Platform API URL. Default: `https://platform.thatopen.com` (production). Pass `https://dev.platform.thatopen.com` to target the dev environment.
-- `--local` — Save credentials to `.thatopen` in the current directory instead of the global config. Use this inside a project to override the global token for that project only.
-
-**Examples:**
-```bash
-thatopen login --token my-token
-thatopen login --token my-token --local
-npm run login -- --token my-token    # from inside a scaffolded project
-```
+---
+description: "Authenticate with the ThatOpen platform by validating an access token against the API. Saves credentials globally (~/.thatopen/config.json) by default, or locally to the project's .thatopen file with --local. Local config takes priority over global."
+---
+
+## thatopen login
+
+Validates an access token against the platform API and saves the credentials. Run this once globally before using any other command, or per-project with `--local`.
+
+To get a token:
+1. Go to [https://platform.thatopen.com](https://platform.thatopen.com)
+2. In the header, click **Data**
+3. Find the **Tokens** card and create a new token
+4. Enable the permissions: **Apps**, **Components**, and **Storage**
+5. Copy the token
+
+**Usage:**
+```bash
+thatopen login --token <token> [flags]
+```
+
+**Flags:**
+
+- `--token <token>` — Access token from the dashboard. Required.
+- `--api-url <url>` — Platform API URL. Default: `https://platform.thatopen.com` (production). Pass `https://dev.platform.thatopen.com` to target the dev environment.
+- `--local` — Save credentials to `.thatopen` in the current directory instead of the global config. Use this inside a project to override the global token for that project only.
+
+**Examples:**
+```bash
+thatopen login --token my-token
+thatopen login --token my-token --local
+npm run login -- --token my-token    # from inside a scaffolded project
+```

package/docs/cli/publish.md

@@ -1,31 +1,31 @@
----
-description: "Build and upload the project to the platform. Automatically detects app vs cloud component from the local .thatopen config. On first publish, saves the assigned item ID back to .thatopen so subsequent runs update the same item instead of creating a new one."
----
-
-## thatopen publish
-
-Builds the project and uploads it to the platform. Works for both apps and cloud components — the project type is read from `.thatopen` (`itemType: APP | COMPONENT`).
-
-First publish creates the item and auto-saves its ID to `.thatopen`. Subsequent publishes update that same item.
-
-**Usage:**
-```bash
-thatopen publish [flags]
-```
-
-**Flags:**
-
-- `--name <name>` — Item name on the platform. Defaults to `name` in `package.json`.
-- `--version-tag <tag>` — Version tag. Defaults to `version` in `package.json`.
-- `--app-id <id>` — Target an existing app by ID (overrides `.thatopen`).
-- `--component-id <id>` — Target an existing cloud component by ID (overrides `.thatopen`).
-- `--skip-build` — Skip the build step and upload the existing `dist/bundle.js`.
-- `--icon <path>` — Path to an icon file (PNG, WebP, or ICO, max 512 KB). Saved to `.thatopen` for future publishes.
-
-**Examples:**
-```bash
-thatopen publish
-thatopen publish --version-tag 2.0.0
-thatopen publish --skip-build
-thatopen publish --icon assets/icon.png
-```
+---
+description: "Build and upload the project to the platform. Automatically detects app vs cloud component from the local .thatopen config. On first publish, saves the assigned item ID back to .thatopen so subsequent runs update the same item instead of creating a new one."
+---
+
+## thatopen publish
+
+Builds the project and uploads it to the platform. Works for both apps and cloud components — the project type is read from `.thatopen` (`itemType: APP | COMPONENT`).
+
+First publish creates the item and auto-saves its ID to `.thatopen`. Subsequent publishes update that same item.
+
+**Usage:**
+```bash
+thatopen publish [flags]
+```
+
+**Flags:**
+
+- `--name <name>` — Item name on the platform. Defaults to `name` in `package.json`.
+- `--version-tag <tag>` — Version tag. Defaults to `version` in `package.json`.
+- `--app-id <id>` — Target an existing app by ID (overrides `.thatopen`).
+- `--component-id <id>` — Target an existing cloud component by ID (overrides `.thatopen`).
+- `--skip-build` — Skip the build step and upload the existing `dist/bundle.js`.
+- `--icon <path>` — Path to an icon file (PNG, WebP, or ICO, max 512 KB). Saved to `.thatopen` for future publishes.
+
+**Examples:**
+```bash
+thatopen publish
+thatopen publish --version-tag 2.0.0
+thatopen publish --skip-build
+thatopen publish --icon assets/icon.png
+```

package/docs/cli/run.md

@@ -1,26 +1,26 @@
----
-description: "Build and run a cloud component locally as a child process, mirroring the backend execution environment. Accepts execution parameters as JSON via --params, validates them against declarations.json, and streams progress output to the terminal."
----
-
-## thatopen run
-
-Builds and executes a cloud component locally, replicating what the platform's cloud engine does. Useful for testing component logic and parameters before publishing.
-
-Execution output (`MESSAGE`, `PROGRESS`, `SUCCESS`, `FAIL`) is streamed to the terminal with elapsed time.
-
-**Usage:**
-```bash
-thatopen run [flags]
-```
-
-**Flags:**
-
-- `--params <json>` — Execution parameters as a JSON string. Default: `'{}'`. Validated against `declarations.json` if present (warns, does not fail).
-- `--skip-build` — Skip the build step and run the existing `dist/bundle.js`.
-
-**Examples:**
-```bash
-thatopen run
-thatopen run --params '{"fileId": "abc123"}'
-thatopen run --skip-build
-```
+---
+description: "Build and run a cloud component locally as a child process, mirroring the backend execution environment. Accepts execution parameters as JSON via --params, validates them against declarations.json, and streams progress output to the terminal."
+---
+
+## thatopen run
+
+Builds and executes a cloud component locally, replicating what the platform's cloud engine does. Useful for testing component logic and parameters before publishing.
+
+Execution output (`MESSAGE`, `PROGRESS`, `SUCCESS`, `FAIL`) is streamed to the terminal with elapsed time.
+
+**Usage:**
+```bash
+thatopen run [flags]
+```
+
+**Flags:**
+
+- `--params <json>` — Execution parameters as a JSON string. Default: `'{}'`. Validated against `declarations.json` if present (warns, does not fail).
+- `--skip-build` — Skip the build step and run the existing `dist/bundle.js`.
+
+**Examples:**
+```bash
+thatopen run
+thatopen run --params '{"fileId": "abc123"}'
+thatopen run --skip-build
+```