@thatopen/services 0.18.0 → 0.19.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 },
@@ -278,7 +298,7 @@ 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.
+   (dashboard → Data → API Tokens). Same secrecy rules as always.
 2. Connect with `socket.io-client` and subscribe, then publish:
 
 ```bash
@@ -288,7 +308,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 +349,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/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.19.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/index.ts

@@ -30,7 +30,9 @@ export interface CDENamingSchema {
     separator: string;
     segments: CDENamingSegment[];
 }
-export interface CDEFile extends Omit<Item, 'creatingUser'> {
+// `Base` now declares `createdBy` itself (the field the API actually
+// returns); this narrows it to the string the CDE panels render.
+export interface CDEFile extends Omit<Item, 'createdBy'> {
     createdBy: string;
     metadata: Record<string, CDEMetadataValue>;
     versions?: ItemVersion[];

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