@thatopen/services 0.18.0 → 0.20.0

package/dist/types/base.d.ts

@@ -2,7 +2,15 @@ export interface Base {
     _id: ObjectId;
     createdAt: Date;
     updatedAt?: Date;
-    creatingUser: ObjectId;
+    /**
+     * The human user who performed the action (audit trail). This used to be
+     * declared as a required `creatingUser`, a field the API has never
+     * returned — the server sends `createdBy`, optionally. Matching the wire
+     * is what a type is for.
+     */
+    createdBy?: ObjectId;
+    /** The human user who last updated the entity (audit trail). */
+    lastUpdatedBy?: ObjectId;
     creatingToken?: ObjectId;
     archived?: boolean;
 }

package/dist/types/notifications.d.ts

@@ -1,5 +1,7 @@
-export type NotificationCategoryDto = 'automation' | 'invitation';
-export type NotificationTypeDto = 'automation.run.started' | 'automation.run.finished' | 'invitation.added' | 'invitation.accepted' | 'project.role_changed';
+export type NotificationCategoryDto = 'automation' | 'invitation' | 'file';
+export type NotificationTypeDto = 'automation.run.started' | 'automation.run.finished' | 'invitation.added' | 'invitation.accepted' | 'project.role_changed' | 'project.transfer.proposed'
+/** A file version landed in a project the recipient belongs to. */
+ | 'file.version_added';
 /**
  * One notification as the API returns it.
  *

package/docs/ai-quickstart.md

@@ -51,8 +51,8 @@ Steps 0–2 are identical for both; they diverge only at `create` (step 3) and h
 
 - **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 → Account → Tokens → create → copy.**
-  (The Data overview shows the same Tokens card; both paths work.)
+  → **https://platform.thatopen.com/dashboard/data → API Tokens → Add → copy.**
+  (Account Settings — avatar menu → Account Settings → API Tokens — shows the same card.)
   Ask the user to paste it. **Never print it back, never write it into a file, never commit it.**
 
 ## 1. Install the CLI
@@ -64,7 +64,7 @@ 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**
-→ **Account → Tokens** → create → copy (the Data overview shows the same card). Ask the
+→ **Data → API Tokens** → Add → copy (Account Settings shows the same card). Ask the
 user to paste it, then run:
 
 ```bash
@@ -81,6 +81,22 @@ first: the next step's install pulls the private `@thatopen-platform/*-beta` pac
 `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.
 
+### The two credentials, side by side (misusing them is the classic first failure)
+
+| | **Platform API token** | **User session JWT** |
+|---|---|---|
+| Where it comes from | Dashboard → Data → API Tokens | The platform session (Auth0); inside an app, `PlatformClient.fromPlatformContext()` |
+| Lifetime | Long-lived until revoked | Hours |
+| Client | `EngineServicesClient` | `PlatformClient` (extends the other, so it can do both) |
+| Can | Files, folders, versions, components, executions — anything with an explicit `projectId` | All of that **plus** the JWT-only routes: `listProjects`, `getProject`, `getProjectData`, `checkPermission`, notifications |
+| Cannot | The JWT-only routes above — they identify a *person*, a token identifies a *token* | Run unattended: it expires with the session |
+| How it travels | `Authorization: Bearer` (the CLI does this for you); the `?accessToken=` query form is legacy | `Authorization: Bearer` |
+
+The failure mode this table prevents: building a service on an API token and discovering
+that `checkPermission` or `listProjects` answers 401 — not because of a bug, but because
+those questions are only answerable about a person. If a feature needs them unattended,
+that is a platform gap to report, not a header to keep fiddling with.
+
 ## 3. Scaffold a beta project
 
 **[app]**
@@ -190,7 +206,11 @@ Copy this skeleton. It is the boot of an app that works.
 async function main() {
   const client = PlatformClient.fromPlatformContext();
 
-  // 1 ── built-ins registered, UI shell up
+  // 1 ── built-ins registered, UI shell up. This is the FULL globals set a
+  //      built-in may ask for: OBC, OBF, BUI, THREE, FRAGS, MARKERJS (plus
+  //      CUI only if your app still uses the deprecated @thatopen/ui-obc).
+  //      Only OBC and BUI are strictly required, but a built-in that needs
+  //      a missing one fails at init, so pass everything you import.
   const { components } = await client.setup<OBC.Components>(
     { OBC, OBF, BUI, THREE, FRAGS, MARKERJS },
     { uuid: UIManager.uuid },
@@ -277,8 +297,11 @@ system: the platform relays messages between app tabs and external tools.
 
 To command the app from outside (a script, an MCP server, your own tool):
 
-1. The user creates a **platform token** with the **API** permission
-   (dashboard → Account → Tokens). Same secrecy rules as always.
+1. The user creates a **platform token** (dashboard → Data → API Tokens). Same
+   secrecy rules as always. The token itself needs no special permission: what
+   the channel checks is the token owner's role in the project, which must allow
+   **API calls**. Project Admin and Member have it by default; a custom role
+   needs it ticked.
 2. Connect with `socket.io-client` and subscribe, then publish:
 
 ```bash
@@ -288,7 +311,13 @@ npm i socket.io-client   # in the external tool's own project, not the app
 ```js
 import { io } from "socket.io-client";
 
-const socket = io(`https://platform.thatopen.com?accessToken=${process.env.THATOPEN_TOKEN}`);
+// WebSocket-only matters: the default long-polling handshake spreads several
+// HTTP requests across the platform's load-balanced instances and can die
+// before it upgrades. The token rides the auth payload, not the URL.
+const socket = io("https://platform.thatopen.com", {
+  transports: ["websocket"],
+  auth: { accessToken: process.env.THATOPEN_TOKEN },
+});
 // While iterating with `thatopen serve`, OMIT appId (the dev channel is keyed
 // to the account); pass the appId once the app is published.
 socket.emit("channelSubscribe", { projectId, appId, kind: "cli" });
@@ -323,6 +352,32 @@ is the reply. The full walkthrough (typed contracts, collaboration events,
 presence) is `node_modules/@thatopen/services/src/core/examples/channel.ts`,
 indexed in the client API index you already loaded.
 
+## 5c. The desktop MCP server: `thatopen mcp`
+
+The raw socket above is for tools you write. For an LLM on the desktop (Claude
+Desktop, Claude Code, anything that speaks MCP), the CLI ships the same bridge
+as a ready-made MCP server over stdio:
+
+```json
+{
+  "mcpServers": {
+    "thatopen-platform": {
+      "command": "npx",
+      "args": ["-y", "@thatopen/services", "mcp"]
+    }
+  }
+}
+```
+
+Credentials come from `thatopen login` (`~/.thatopen/config.json`); to inject
+them instead, set `THATOPEN_TOKEN` and `THATOPEN_API_URL` in the server's
+`env`. Two tools: `platform-status` (can the platform be reached, is the
+subscription alive) and `send-app-command` (publish a command to a running
+app — `ping`, `get-loaded-models`, or whatever the app declares — and return
+its reply). The project is named per call, by id or dashboard URL, so one MCP
+session can drive whichever project the user has open; while iterating with
+`thatopen serve`, `app_id` is omitted, same rule as the raw socket.
+
 ## 6. Publish (when ready)
 
 ```bash

package/docs/cli/mcp.md

@@ -0,0 +1,41 @@
+---
+description: "Start an MCP server over stdio that lets an LLM on the desktop (Claude Desktop, Claude Code, any MCP client) drive a running That Open app through the platform channel: send it commands and read the replies."
+---
+
+## thatopen mcp
+
+Runs an MCP (Model Context Protocol) server on stdio. Register it in an MCP
+client's config and the LLM can command a running That Open app through the
+platform channel — the same relay the app's `src/setups/channel.ts` listens
+to, as one external channel of kind `mcp`.
+
+**Usage (in the MCP client's config, not a terminal):**
+
+```json
+{
+  "mcpServers": {
+    "thatopen-platform": {
+      "command": "npx",
+      "args": ["-y", "@thatopen/services", "mcp"]
+    }
+  }
+}
+```
+
+**Credentials:** resolved like every other CLI command — the project's
+`.thatopen`, then `~/.thatopen/config.json` from `thatopen login`. Or inject
+`THATOPEN_TOKEN` and `THATOPEN_API_URL` through the MCP server's `env`.
+
+**Tools exposed:**
+
+- `platform-status` — which API the server points at, whether credentials were
+  found, and whether the channel subscription works. The first call to make
+  when another tool fails.
+- `send-app-command` — publish a command (`ping`, `get-loaded-models`, or
+  whatever the app declares in `AppCommands`) to a running app and return its
+  reply. Takes the project per call (id or dashboard URL); `app_id` is omitted
+  while the app runs under `thatopen serve` and passed once it is published.
+
+**The app must be open.** `delivered: 0` means no tab of that app has the
+channel joined — the LLM is told to ask the user to open or reload the app
+tab, the same rule as the raw socket in the quickstart's section 5b.

package/docs/cli/paths.json

@@ -11,6 +11,10 @@
     "path": "docs/cli/login.md",
     "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."
   },
+  {
+    "path": "docs/cli/mcp.md",
+    "description": "Start an MCP server over stdio that lets an LLM on the desktop (Claude Desktop, Claude Code, any MCP client) drive a running That Open app through the platform channel: send it commands and read the replies."
+  },
   {
     "path": "docs/cli/publish.md",
     "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."

package/docs/client/paths.json

@@ -35,6 +35,10 @@
     "path": "src/core/examples/hidden-files.ts",
     "description": "Hidden file lifecycle — create, get, list by parent, download, and delete."
   },
+  {
+    "path": "src/core/examples/history.ts",
+    "description": "History and recipes — a project's connected documents (Revit, AutoCAD…), their version timelines, change requests (suggestions), and recipes: scripts that write suggestions in an app's native language."
+  },
   {
     "path": "src/core/examples/icons.ts",
     "description": "Item icon management — upload, download, and remove icons on any item (file, app, or component)."

package/docs/platform-token.md

@@ -8,7 +8,7 @@ here rather than in each of them.
 Say this to the user, and wait:
 
 > "To log in I need a That Open Platform **access token**. You create it yourself:
-> **https://platform.thatopen.com/dashboard → Account → Tokens → create → copy** (the Data overview shows the same card), then paste it
+> **https://platform.thatopen.com/dashboard/data → API Tokens → Add → copy** (Account Settings shows the same card), then paste it
 > here."
 
 **Never print it back, never write it into a file, never commit it.** Not into a script, not into a

package/package.json

@@ -15,7 +15,7 @@
     "access": "public"
   },
   "private": false,
-  "version": "0.18.0",
+  "version": "0.20.0",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "types": "dist/index.d.ts",
@@ -48,6 +48,7 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.27.7",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@thatopen/components": "~3.4.0",
     "@thatopen/components-front": "~3.4.0",
     "@thatopen/fragments": "~3.4.0",
@@ -70,7 +71,8 @@
     "vite": "^5.2.0",
     "vite-plugin-dts": "^3.9.1",
     "vite-plugin-eslint": "^1.8.1",
-    "vitest": "^4.1.4"
+    "vitest": "^4.1.4",
+    "zod": "^3.25.76"
   },
   "dependencies": {
     "@types/geojson": "7946.0.16",

package/src/built-in/GISManager/example.ts

@@ -85,8 +85,37 @@ await gis.enableTiles();
   makes the see-through effect possible. On other hosts they are added to the
   scene directly and stay opaque. You do not need to do anything for this: the
   component detects it.
+
+  On those deferred hosts the tiles also dissolve gradually near the camera's far
+  plane instead of ending in a hard edge. `horizonFade` is the fraction of the far
+  distance over which this happens: with the default `0.8` and a far plane at
+  1000, the tiles are fully visible up to 200 and fully transparent at 1000. It
+  combines with the see-through opacity, and `0` turns it off. While the map is
+  loaded the fade is a fraction of `mapFar` (see below), not of the camera's own
+  far plane.
+
+  While the tiles are loaded, the empty background behind them is also painted
+  as a sky: a gradient from `skyHorizonColor` (default `#d7e3ee`, a light hazy
+  blue) at the horizon to `skyZenithColor` (default `#6a9bd1`) straight up, so
+  the tiles dissolve into the horizon colour. Set `sky = false` to keep the
+  background as it is. Like the fade, it only exists on deferred hosts.
+
+  To let the map reach the horizon, `GISManager` takes over the far plane of the
+  world's cameras while the tiles are loaded: `mapFar`, `10000` by default. With
+  the default `horizonFade` of `0.8` the map is fully visible up to 2 km and
+  fades out until 10 km. A far plane the application or the user set is only
+  remembered while the map is loaded and comes back when `disableTiles()` runs
+  (a larger far set by code that grows it, for example when it loads a large
+  point cloud, is respected, and kept). Setting `mapFar` while the map is loaded
+  applies immediately. This works on every host, deferred or not.
 */
 
+gis.horizonFade = 0.4;
+gis.mapFar = 15000;
+gis.skyHorizonColor = "#e8d9c5";
+gis.skyZenithColor = new THREE.Color(0x4f86c6);
+gis.sky = true;
+
 gis.onStateChanged.add((state) => console.log("tiles visible:", state.tilesVisible));
 gis.setTilesOpacity(0.6);
 

package/src/built-in/UIManager/src/settings-panel/example.ts

@@ -79,7 +79,10 @@ components.get(UIManager).init();
   ### 🤖 What the default panel manages automatically
 
   **Graphics** — point/line/edge styling, background, shadows, ambient
-  occlusion — whatever `top-viewer` supports, persisted across reloads.
+  occlusion — whatever `top-viewer` supports, persisted across reloads. When the
+  app uses `GISManager`, a "GIS Map" group also appears, with the sky on/off, the
+  horizon fade (how far before the camera's far plane the map dissolves, 0 = hard
+  cut) and the sky's horizon and zenith colours.
 
   **Clip styling** — fill/edge color, opacity, width for the clip tool,
   shared live with `top-viewer-toolbar`'s clip button.

package/src/built-in/index.ts

@@ -1666,6 +1666,64 @@ declare class _GISManager extends OBC.Component {
     private _tilesOpacity;
     private _fadeTarget;
     private _fadeQuad;
+    private _horizonTarget;
+    private _horizonQuad;
+    /**
+     * Fraction (0–1) of the camera's far distance over which the 3D tiles dissolve
+     * into what is behind them, instead of ending in a hard edge at the far plane:
+     * the tiles are fully visible up to `far * (1 - horizonFade)` and fully
+     * transparent at `far`. Default 0.8. `0` turns it off (opaque tiles are drawn
+     * straight into the frame at opacity 1, as before). Combines with
+     * `setTilesOpacity`: final alpha = opacity × fade. Deferred hosts only — where
+     * the tiles are added to the scene directly there is no fade. Vector layers
+     * are not faded.
+     */
+    horizonFade: number;
+    private readonly _far;
+    private _farCameras;
+    /**
+     * Far plane (distance) the world's cameras get while the 3D tiles are loaded, so
+     * the map reaches the horizon. Default `10000`. Changing it while the map is
+     * loaded takes effect immediately. `horizonFade` is a fraction of this far while
+     * the map is loaded (with `0.8`, the map fades from 2 km to 10 km).
+     *
+     * The camera's own far plane (e.g. the Settings panel's "Far plane") is
+     * overridden while the map is loaded: it is remembered, not applied, and comes
+     * back when the map is unloaded. Code that grows the far plane itself while the
+     * map is loaded still works: a larger far than `mapFar` is left alone, and is
+     * kept on unload.
+     */
+    get mapFar(): number;
+    set mapFar(far: number);
+    /** True while the map owns the cameras' far plane (the 3D tiles are loaded). */
+    get farOverridden(): boolean;
+    /** The far plane the user asked for, remembered while `farOverridden` (otherwise the cameras hold it). */
+    get userCameraFar(): number;
+    /** Records the far plane the user wants; not applied until the map is unloaded. Only meaningful while `farOverridden`. */
+    setUserCameraFar(far: number): void;
+    private _resolveFarCameras;
+    /**
+     * Shows a sky gradient behind everything while the 3D tiles are loaded: the
+     * empty background (pixels nothing has drawn to) goes from `skyHorizonColor` at
+     * the horizon to `skyZenithColor` straight up, so the tiles, dissolving with
+     * `horizonFade`, melt into the horizon colour. Below the horizon it is the
+     * horizon colour; an orthographic camera sees one flat colour. Default `true`;
+     * `false` leaves the background untouched. Deferred hosts only — elsewhere
+     * there is no sky. Drawn behind the vector layers and the tiles.
+     */
+    sky: boolean;
+    private readonly _skyHorizon;
+    private readonly _skyZenith;
+    private _skyHorizonColor;
+    private _skyZenithColor;
+    private _skyPass;
+    private static _setSkyRgb;
+    /** Sky colour at the horizon (any CSS colour string, hex number or `THREE.Color`). Default `"#d7e3ee"`, a light hazy blue. */
+    get skyHorizonColor(): THREE.ColorRepresentation;
+    set skyHorizonColor(color: THREE.ColorRepresentation);
+    /** Sky colour straight up. Default `"#6a9bd1"`, a deeper blue. */
+    get skyZenithColor(): THREE.ColorRepresentation;
+    set skyZenithColor(color: THREE.ColorRepresentation);
     private _passRegistered;
     private _ensureOcclusionPass;
     private readonly _occlusion;

package/src/cli/templates/app/README.md

@@ -40,7 +40,7 @@ Apps run inside the That Open Platform within a project, not as standalone websi
 To develop locally:
 
 1. Run `npm run dev` — watches source with esbuild and serves the bundle on port 4000.
-2. Open your project on the platform and click the debug button.
+2. Open your project on the platform, click the Local App icon, then Get Started.
 3. Live reload is enabled — save a file to rebuild automatically.
 
 **Important**: use `npm run dev` (it runs `thatopen serve` under the hood). Do NOT run

package/src/core/examples/history.ts

@@ -0,0 +1,103 @@
+// description: "History and recipes — a project's connected documents (Revit, AutoCAD…), their version timelines, change requests (suggestions), and recipes: scripts that write suggestions in an app's native language."
+import { EngineServicesClient } from '../client';
+import type { Recipe } from '../recipes';
+
+// The mental model, in three sentences:
+// 1. Every connected document (a Revit model, an AutoCAD drawing) has its
+//    version history: who synced, when, what changed.
+// 2. Nobody writes in somebody else's document. Changes arrive as SUGGESTIONS
+//    (create / modify / delete native data) that the owner accepts or
+//    dismisses in the native app. That is why running any of this is safe.
+// 3. A RECIPE is a script that writes suggestions in an application's own
+//    language. Anything that wants to change a Revit document uses a Revit
+//    recipe to say it in Revit's words.
+
+export async function readTheProjectHistory(
+  client: EngineServicesClient,
+  projectId: string,
+) {
+  const history = client.history(projectId);
+
+  // Which documents are connected, and from which application.
+  const docs = await history.docs();
+  for (const { source, docId } of docs) {
+    const doc = history.doc(source, docId);
+
+    // The timeline is ordered by the version graph, oldest first, with
+    // `ordinal` filled in. The last entry is the head.
+    const timeline = await doc.timeline();
+    const head = timeline[timeline.length - 1];
+    console.log(
+      `${source}-${docId}: ${timeline.length} versions, head by ${head?.author}`,
+    );
+
+    // A version's geometry: full exports ARE the model file; ordinary
+    // versions carry a hidden delta.
+    if (head?.deltaId) await doc.delta(head);
+    else if (head?.full) await doc.model();
+
+    // The change requests waiting for the document's owner.
+    const pending = await doc.pendingSuggestions();
+    console.log(`${pending.length} suggestions pending`);
+  }
+}
+
+// A recipe is its manifest plus one function. The settingsSchema is what apps
+// render as a form — anything naming an EXISTING thing must be an enum the
+// app fills, so people pick instead of typing names.
+const pointsToBlocks: Recipe<{ layer: string; block: string }> = {
+  name: 'points-to-autocad-blocks',
+  description: 'Places an AutoCAD block on every input point.',
+  to: 'autocad',
+  inputs: ['points'],
+  runtime: 'browser',
+  settingsSchema: {
+    type: 'object',
+    properties: {
+      layer: { type: 'string' },
+      block: { type: 'string' },
+    },
+    required: ['layer', 'block'],
+  },
+  rules: [{ reads: 'input points', proposes: 'one block per point' }],
+  async run({ input, settings }) {
+    const points = input as { x: number; y: number; z: number }[];
+    // Build the suggestion payload (a .frag with envelope revitflow/op@2,
+    // one item per change, attributes in the TARGET's own vocabulary).
+    // The payload builder lives in the fragments toolkit; omitted here.
+    const payload = await buildOpFrag(points, settings);
+    return {
+      title: `Place ${points.length} ${settings.block} blocks`,
+      verb: 'add',
+      targets: points.length,
+      payload,
+      ruleTallies: [{ read: points.length, proposed: points.length }],
+    };
+  },
+};
+
+export async function runARecipe(
+  client: EngineServicesClient,
+  projectId: string,
+) {
+  client.recipes.register(pointsToBlocks);
+
+  // Catalogs filter by target application: "who can speak autocad?".
+  client.recipes.list({ to: 'autocad' });
+
+  // Running is always safe: it only queues a suggestion on the target
+  // document. Nothing changes in AutoCAD until its owner applies it there.
+  const { suggestion } = await client.recipes.run('points-to-autocad-blocks', {
+    projectId,
+    target: { source: 'autocad', docId: 'site-plan' },
+    input: [{ x: 0, y: 0, z: 0 }],
+    settings: { layer: 'DETECTORS', block: 'SIEMENS-FDO181' },
+    author: 'recipe:points-to-autocad-blocks',
+  });
+  console.log(`queued suggestion ${suggestion.opId}`);
+}
+
+declare function buildOpFrag(
+  points: { x: number; y: number; z: number }[],
+  settings: { layer: string; block: string },
+): Promise<Blob>;