@thatopen/services 0.7.0 → 0.9.0

package/dist/types/notifications.d.ts

@@ -0,0 +1,54 @@
+export type NotificationCategoryDto = 'automation' | 'invitation';
+export type NotificationTypeDto = 'automation.run.started' | 'automation.run.finished' | 'invitation.added' | 'invitation.accepted' | 'project.role_changed';
+/**
+ * One notification as the API returns it.
+ *
+ * Ids are strings and timestamps are ISO-8601 strings, because that is what
+ * JSON carries. The producer payload is deliberately absent: `title`, `body`
+ * and `link` are built server-side, so the data behind them is an internal
+ * detail rather than part of this contract.
+ */
+export interface NotificationDto {
+    _id: string;
+    accountId: string;
+    type: NotificationTypeDto;
+    category: NotificationCategoryDto;
+    title: string;
+    body: string;
+    link?: string;
+    /** Silenced by the recipient: still listed, but no badge and no channel. */
+    muted: boolean;
+    readAt: string | null;
+    createdAt: string;
+}
+/** `nextCursor` is opaque — pass it back verbatim. Null means the last page. */
+export interface NotificationPageDto {
+    items: NotificationDto[];
+    nextCursor: string | null;
+}
+/** Excludes muted and already-read notifications: this is the bell badge. */
+export interface UnreadCountDto {
+    count: number;
+}
+export interface MarkNotificationsReadResultDto {
+    updated: number;
+}
+/** A user's opt-in to one automation's runs, as the API returns it. */
+export interface NotificationSubscriptionView {
+    _id: string;
+    accountId: string;
+    hookId: string;
+    /** Absent for personal automations, which belong to an account. */
+    projectId?: string;
+    filter: NotificationSubscriptionFilter;
+    channels?: {
+        email?: boolean;
+    };
+    createdAt: string;
+    updatedAt?: string;
+}
+/**
+ * `failures` suppresses started events entirely and only passes a finished
+ * run that did not succeed.
+ */
+export type NotificationSubscriptionFilter = 'all' | 'failures';

package/dist/vite-env.d.ts

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

package/docs/ai-quickstart.md

@@ -87,6 +87,16 @@ thatopen create my-app --beta
 cd my-app
 ```
 
+**[app, showing a Revit model's commit history]** If what they asked for is a viewer of the
+revit-flow history, scaffold it directly. Do not build it by hand: the wiring is four additions in
+three places and the ORDER of them is load-bearing (see the boot order section below). This ships
+it already correct, opening on the History layout.
+
+```bash
+thatopen create my-app --beta --history
+cd my-app
+```
+
 **[component]**
 ```bash
 thatopen create my-component -t cloud-component --beta
@@ -110,6 +120,17 @@ 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.
 
+If it does not open by itself, or the user closes the tab, the app you are serving from this
+machine lives at:
+
+```
+https://platform.thatopen.com/dashboard/projects/<PROJECT_ID>/apps/local-app
+```
+
+Substitute the project id. That is the local app running inside the platform's own UI, against
+the project's real data. Send the user there rather than to a bare localhost port, which is the
+app without the platform around it.
+
 > **`npx tsc --noEmit` reports errors in a fresh beta scaffold, and they are not real.** You will see
 > a handful of `Cannot find module '@thatopen/components'` and friends. A beta project aliases those
 > imports to the `@thatopen-platform/*-beta` packages in `vite.config.js`, which bare `tsc` does not
@@ -126,6 +147,101 @@ npm run run        # executes the component locally against the platform (no bro
 ```
 Runs `main()` in a local emulation of the cloud engine so you can iterate before publishing.
 
+## THE BOOT ORDER. Read this before you write a line of an app.
+
+**This is where apps break, and the error never names the real cause.** An app boots in four
+stages, and a built-in that touches models or the 3D scene must be initialised in the LAST one.
+Call it where it reads naturally, right after `client.setup`, and you get:
+
+```
+Error: FragmentsManager not initialized. Call init() first.
+Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'onHighlight')
+Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'onClear')
+```
+
+None of which says "you called this too early". The app renders, the panel mounts, and it sits
+there inert.
+
+**Why.** `FragmentsManager` is initialised inside `top-app`'s own `setup` callback, and the 3D
+world does not exist until `<top-app>` has been added to the DOM and `top-viewer` has built it.
+Both of those happen well after `client.setup` returns. Any manager that reads model files or
+colours elements reaches for them the moment it starts.
+
+**The order, and it is not negotiable:**
+
+1. `client.setup(...)` with every built-in you need, then `components.get(UIManager).init()`
+2. `app.setup = ...`, which is where `FragmentsManager.init` goes, and append `<top-app>`
+3. `await firstWorld(...)`, so the world exists
+4. **only now**, `init(client)` on the model-facing managers
+
+Copy this skeleton. It is the boot of an app that works.
+
+```ts
+async function main() {
+  const client = PlatformClient.fromPlatformContext();
+
+  // 1 ── built-ins registered, UI shell up
+  const { components } = await client.setup<OBC.Components>(
+    { OBC, OBF, BUI, THREE, FRAGS, MARKERJS },
+    { uuid: UIManager.uuid },
+    { uuid: GitHistoryManager.uuid },        // and any other built-in you use
+  );
+  components.get(UIManager).init();
+
+  const viewerEl = document.createElement("top-viewer");
+  const app = document.createElement("top-app") as any;
+
+  // 2 ── this callback is what initialises FragmentsManager. Nothing that needs
+  //      fragments may run before it has resolved.
+  app.setup = (waitUntil: (p: Promise<void>, label?: string) => void) => {
+    waitUntil(
+      (async () => {
+        const fragments = components.get(OBC.FragmentsManager);
+        const workerUrl = await FRAGS.FragmentsModels.getWorker();
+        fragments.init(await FRAGS.toClassicWorker(workerUrl), { classicWorker: true });
+      })(),
+      "Fragments Core",
+    );
+    return { components, client };
+  };
+
+  app.elements = { viewer: () => BUI.html`${viewerEl}` };
+  app.layouts = { Main: { template: `"viewer" 1fr / 1fr` } };
+  app.layout = "Main";
+  (document.getElementById("that-open-app") ?? document.body).appendChild(app);
+
+  // 3 ── the world is created asynchronously by top-viewer. Wait for it.
+  await firstWorld(components.get(OBC.Worlds));
+
+  // 4 ── ONLY NOW. Everything above had to have happened first.
+  await components.get(GitHistoryManager).init(client);
+
+  // ...and from here, the real layouts, panels and elements.
+}
+
+/** Resolves with the first world once it exists (top-viewer creates it async). */
+function firstWorld(worlds: any): Promise<any> {
+  const existing = [...worlds.list.values()][0];
+  if (existing) return Promise.resolve(existing);
+  return new Promise((resolve) => {
+    const handler = ({ value }: any) => {
+      worlds.list.onItemSet.remove(handler);
+      resolve(value);
+    };
+    worlds.list.onItemSet.add(handler);
+  });
+}
+```
+
+**Two more traps in the same family:**
+
+- **One stable `top-viewer` node, held in a variable and returned by reference** from every
+  `elements.viewer()` call. Creating a fresh element on each render disposes the world and
+  builds another one, and everything wired to the old one goes quiet.
+- **Registering a built-in is not the same as initialising it.** `client.setup` makes
+  `<top-git-history>` resolvable; `init(client)` is what fills it. A panel that mounts and stays
+  empty is usually the second one missing, not the first.
+
 ## 5. Then build — read the in-project agent guide
 
 The scaffold is real, working code — a complete viewer **[app]** or a runnable `main()`
@@ -163,5 +279,8 @@ component, once added to a project, is then triggered by an app or an automation
 - **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.
+- **Do the thing they asked for.** If the request already says what to build, build it. Proposing a
+  four-point plan and waiting for approval to do what was just requested costs the user a whole turn
+  and buys nothing. Stop and ask only when you are about to change files you did not create, when
+  the request can be read two ways that mean different work, or when the next step is destructive.
 - 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
+```

package/docs/cli/serve.md

@@ -1,43 +1,43 @@
----
-description: "Start a local dev server for a browser app. Uses esbuild in watch mode and serves the IIFE bundle on port 4000 with SSE live reload. To connect: open the project on platform.thatopen.com, click the Local App icon, then Get Started."
----
-
-## thatopen serve
-
-Builds the app in watch mode and serves the IIFE bundle locally. On every save, esbuild rebuilds and the platform reloads the bundle automatically via SSE.
-
-Does **not** open a browser tab — the app runs inside the platform iframe. Open your project on the platform, then click the debug button to connect it to the local server.
-
-**Usage:**
-```bash
-thatopen serve [flags]
-```
-
-**Flags:**
-
-- `--port <port>` — Port to serve the bundle on. Default: `4000`.
-
-**Endpoints served:**
-
-- `GET /bundle.js` — The compiled IIFE bundle.
-- `GET /bundle.js.map` — Source map.
-- `GET /events` — SSE stream for live reload.
-
-**Example:**
-```bash
-thatopen serve
-thatopen serve --port 4321
-```
-
-**Connecting the platform to your local server:**
-
-1. Go to [https://platform.thatopen.com](https://platform.thatopen.com) and open a project (create one first if needed).
-2. In the top right corner, click the **Local App** icon.
-3. Click **Get Started**.
-
-The platform loads the bundle from port 4000 and renders the app inside the project context, with full access to its models, data, and users. The dev server must be running before opening this URL — if nothing is served on port 4000, the platform will fail to load the app.
-
-The resulting URL follows this pattern:
-```
-https://platform.thatopen.com/dashboard/projects/{projectId}/apps/local-app
-```
+---
+description: "Start a local dev server for a browser app. Uses esbuild in watch mode and serves the IIFE bundle on port 4000 with SSE live reload. To connect: open the project on platform.thatopen.com, click the Local App icon, then Get Started."
+---
+
+## thatopen serve
+
+Builds the app in watch mode and serves the IIFE bundle locally. On every save, esbuild rebuilds and the platform reloads the bundle automatically via SSE.
+
+Does **not** open a browser tab — the app runs inside the platform iframe. Open your project on the platform, then click the debug button to connect it to the local server.
+
+**Usage:**
+```bash
+thatopen serve [flags]
+```
+
+**Flags:**
+
+- `--port <port>` — Port to serve the bundle on. Default: `4000`.
+
+**Endpoints served:**
+
+- `GET /bundle.js` — The compiled IIFE bundle.
+- `GET /bundle.js.map` — Source map.
+- `GET /events` — SSE stream for live reload.
+
+**Example:**
+```bash
+thatopen serve
+thatopen serve --port 4321
+```
+
+**Connecting the platform to your local server:**
+
+1. Go to [https://platform.thatopen.com](https://platform.thatopen.com) and open a project (create one first if needed).
+2. In the top right corner, click the **Local App** icon.
+3. Click **Get Started**.
+
+The platform loads the bundle from port 4000 and renders the app inside the project context, with full access to its models, data, and users. The dev server must be running before opening this URL — if nothing is served on port 4000, the platform will fail to load the app.
+
+The resulting URL follows this pattern:
+```
+https://platform.thatopen.com/dashboard/projects/{projectId}/apps/local-app
+```