@thatopen/services 0.0.1

package/CONTEXT.md

@@ -0,0 +1,258 @@
+# thatopen-services
+
+Client library and CLI for the That Open Platform — a cloud platform for building BIM (Building Information Modeling) software.
+
+## What this repo contains
+
+1. **Library** (`src/core/client.ts`) — `EngineServicesClient`, a TypeScript API client for managing files, folders, apps, cloud components, and executions on the platform.
+2. **CLI** (`src/cli/`) — The `thatopen` command-line tool for scaffolding and publishing apps and cloud components.
+3. **Built-in components** (`src/built-in/`) — Type stubs for platform-provided UI components (AppManager, ViewportManager, etc.) that are fetched and evaluated at runtime.
+
+## Project structure
+
+```
+src/
+  core/client.ts              # EngineServicesClient — the main API class
+  cli/
+    commands/create.ts        # thatopen create — scaffolds new projects
+    commands/serve.ts         # thatopen serve — dev server (esbuild watch + serve)
+    commands/login.ts         # thatopen login — authenticate with the platform
+    commands/publish.ts       # thatopen publish — build and upload to the platform
+    commands/run.ts           # thatopen run — test cloud components locally
+    commands/create-tests.ts  # thatopen create-tests — scaffolds test app + test component
+    commands/serve-tests.ts   # thatopen serve-tests — serves both test projects in parallel
+    templates/                # Template generators for scaffolded projects
+    lib/                      # CLI helper utilities (config, certificates)
+  built-in/index.ts           # Built-in component type stubs + runtime UUID constants
+  types/                      # TypeScript type definitions (items, execution, etc.)
+  index.ts                    # Library entry point (re-exports everything)
+```
+
+## Build system
+
+- **Library** builds to CommonJS (`dist/index.cjs.js`) + ESM (`dist/index.es.js`) + types (`dist/index.d.ts`) via Vite (`vite.config.mts`).
+- **CLI** builds to a single `dist/cli.js` executable via Vite (`vite.config.cli.mts`). It bundles commander, jszip, and all library code.
+- TypeScript strict mode is enabled.
+
+### Commands
+
+```bash
+npm run build          # Full build (library + CLI)
+npm run build:lib      # Library only
+npm run build:cli      # CLI only
+```
+
+### Testing
+
+```bash
+npm run test                      # Run vitest unit tests (HTTP client contract)
+npm run test:watch                # Vitest watch mode
+npm run test:ui                   # Interactive browser test page
+npm run test:cli-build-app        # Scaffold + build a test app
+npm run test:cli-build-component  # Scaffold + build a test cloud component
+npm run test:cli-run-component    # Run the test cloud component locally
+npm run test:cli-build-tests      # Build CLI + scaffold test app & test component into temp/
+npm run test:cli-serve-tests      # Serve the test app and test component's local server in parallel
+```
+
+## Two clients — components vs apps/FE
+
+This package ships two clients with overlapping but intentionally different
+surfaces. Pick the one that matches who's calling.
+
+### `EngineServicesClient`
+**For cloud components running inside the platform.** Authenticates via
+API token by default (`?accessToken=`). Supports local-server execution,
+WebSocket execution progress, built-in component runtime helpers, and the
+low-level HTTP surface. This is what you get via
+`EngineServicesClient.fromPlatformContext()` inside a component bundle.
+
+### `PlatformClient`
+**For apps, frontends, and any caller using a user JWT.** Extends
+`EngineServicesClient`; the API-token-compatible surface is inherited and
+the constructor forces `useBearer: true`. On top, it owns the JWT-only
+routes — `getProject`, `getProjectData`, `checkPermission`,
+`checkPermissionBatch` — which hit `ProjectController` in the backend
+(guarded by JWT) and are not reachable with an access token.
+
+The constructor accepts either a static JWT or a provider function
+(sync or async) that returns the current JWT. The provider is called on
+every request, so Auth0's `getAccessTokenSilently()` and similar
+refreshing sources Just Work:
+
+```ts
+import { PlatformClient } from 'thatopen-services';
+const client = new PlatformClient(
+  () => auth0.getAccessTokenSilently(),
+  'https://api.thatopen.com',
+);
+await client.getProjectData(projectId);
+```
+
+`PlatformClient.fromPlatformContext()` is available for apps running inside
+the platform iframe — it pulls the JWT from
+`window.__THATOPEN_CONTEXT__` and returns a ready-to-use client.
+
+Choose by audience:
+- Component code → `EngineServicesClient` (or `EngineServicesClient.fromPlatformContext()`).
+- App / FE / integration with a user JWT → `PlatformClient`.
+
+## Permissions contract (backend coupling)
+
+The platform API enforces **project-scoped permission checks**: whenever a
+request carries a `projectId` (URL param, query, or body), the backend
+rejects the call if the resource does not belong to that project or the
+caller lacks permission there — regardless of whether the caller has access
+to the same resource in a different project.
+
+Relevant client methods:
+
+- `executeComponent(componentId, executionParams, versionTag?)`: include
+  `projectId` in `executionParams` to scope the execution. The backend
+  validates that the component is linked to that project. Without a
+  `projectId`, the execution runs in the user's personal/ownership scope.
+- `listExecutions(componentId, projectId?)`: pass `projectId` to filter
+  executions to that project's context.
+- `checkPermission({ resourceType, action, resourceId?, projectId? })`:
+  returns `{ hasPermission, scope }`. `scope` is `'global' | 'project' |
+  'entity' | 'none'` — `global` for admin/owner bypass, `project` for a
+  role broad grant, `entity` for a per-entity override, `none` for denied.
+- `checkPermissionBatch(checks)`: evaluates a list of checks in one
+  round-trip. Useful for hydrating action visibility for many rows without
+  N+1 calls.
+
+Per-entity permission overrides (`ResourcePermission.removePermission`,
+`ResourcePermission.appliesToDescendants`) are applied automatically on the
+server side when listing project files/folders — no client change needed.
+
+
+### Publishing to npm
+
+```bash
+yarn create-version   # Build → changeset → version → publish
+```
+
+## Key concepts
+
+### Apps vs Cloud Components
+
+| | Apps | Cloud Components |
+|---|---|---|
+| **Runs in** | Browser (iframe on the platform) | Server (Node.js child process) |
+| **Item type** | `APP` | `TOOL` |
+| **Entry point** | Side effects in `main.ts` (renders UI) | `export async function main()` |
+| **Context** | `window.__THATOPEN_CONTEXT__` provides `{ appId, projectId, accessToken, apiUrl }` | Globals: `thatOpenServices`, `executionParams`, `executionContext` (`{ projectId?, executionId, toolId, toolVersion }`), `executionReporter` (`message/error/progress`). `OBC`, `THREE`, `web-ifc`, `fs` are NOT injected — import them and let the bundler include them. |
+| **Build output** | IIFE `dist/bundle.js` (all deps bundled) | IIFE `dist/bundle.js` (only `thatopen-services` externalized) |
+| **Template** | `bim`, `default`, or `test` | `cloud` or `cloud-test` |
+
+### Authentication
+
+Two modes, controlled by `useBearer` in the constructor:
+- **Query parameter** (default): Sends `accessToken` as a URL query param. Used with platform API tokens.
+- **Bearer header** (`useBearer: true`): Sends as `Authorization: Bearer <token>`. Used with Auth0 JWTs inside platform apps.
+
+### Built-in components
+
+Built-in components are platform-hosted UI modules fetched at runtime. Usage pattern:
+
+```ts
+import { AppManager, ViewportManager } from "thatopen-services";
+
+// Register all library globals once
+client.setBuiltInGlobals({ OBC, OBF, BUI, CUI, THREE, FRAGS });
+
+// Fetch, evaluate, and register with OBC — globals are automatically applied
+await client.initBuiltInComponent(AppManager, components);
+await client.initBuiltInComponent(ViewportManager, components);
+
+// Use via OBC component system
+const app = components.get(AppManager);
+const viewports = components.get(ViewportManager);
+```
+
+Available built-in components:
+
+| Component | Purpose |
+|-----------|---------|
+| `AppManager` | App shell — CSS grid layout with sidebar for switching layouts |
+| `ViewportManager` | Factory for 3D viewports with pre-configured world |
+| `LoadModelButton` | Button + dropdown for loading IFC / Fragments files |
+| `ViewerToolbar` | Toolbar with Show/Hide/Focus/Isolate and color palette |
+| `ModelsPanel` | Panel listing loaded models with search and load button |
+| `ModelsDropdown` | Dropdown selector listing loaded models |
+| `ClassificationsList` | Hierarchical table of IFC classification data |
+| `ClashesList` | Interactive clash detection results with highlighting |
+| `ClippingsList` | Panel listing clipping planes with controls |
+| `LengthMeasuringsList` | Panel listing length measurements with totals |
+| `AreaMeasuringsList` | Panel listing area measurements with totals |
+| `ColorsPalette` | Color picker with Highlighter style swatches |
+| `HighlightersList` | Panel listing Highlighter styles with manage actions |
+| `QtoComparisonList` | Side-by-side quantity comparison for two elements |
+| `QueriesHierarchy` | Recursive multi-level query browser |
+| `CustomViewLegend` | Color legend overlay |
+| `ScreenshotAnnotator` | Modal for annotating screenshots via MarkerJS |
+
+Full API reference with config interfaces, method signatures, and `@example` blocks: `src/built-in/index.ts`.
+
+### Configuration files
+
+- **Global**: `~/.thatopen/config.json` — `{ accessToken, apiUrl }`
+- **Local** (per project): `.thatopen` — `{ accessToken, apiUrl, appId?, componentId?, itemType? }`
+- Local config takes priority. Created by `thatopen login --local`.
+
+## API surface (EngineServicesClient)
+
+### Files
+- `listFiles(filters?)` / `getFile(id, props?)` / `createFile(data)` / `updateFile(id, data)`
+- `archiveFile(id)` / `recoverFile(id)` / `downloadFile(id, params?)` / `getFileMetadata(id, params?)`
+
+### Folders
+- `listFolders(params?)` / `getFolder(id)` / `createFolder(name, parentId?)`
+- `updateFolder(id, params)` / `archiveFolder(id)` / `recoverFolder(id)` / `downloadFolder(id)`
+
+### Components
+- `listComponents(params?)` / `getComponent(id, props?)` / `createComponent(data)` / `updateComponent(id, data)`
+- `archiveComponent(id)` / `recoverComponent(id)` / `downloadComponent(id, params?)` / `downloadComponentBundle(id, params?)`
+
+### Apps
+- `listApps(params?)` / `createApp(data)` / `archiveApp(id)`
+- `downloadApp(id, params?)` / `downloadAppBundle(id, params?)`
+
+### Execution (cloud components)
+- `executeComponent(componentId, params, versionTag?)` — triggers server-side execution, returns `{ executionId }`
+- `abortExecution(executionId)` / `listExecutions(componentId)` / `getExecution(executionId)`
+- `onExecutionProgress(executionId, callback)` — real-time WebSocket subscription
+
+### Built-in components
+- `setBuiltInGlobals(globals)` — registers globals once; subsequent `initBuiltInComponent` calls use them automatically
+- `getBuiltInComponent(name)` — fetches JS bundle by name
+- `initBuiltInComponent(component, components, globals?)` — fetches, evaluates, and registers (uses stored globals if `globals` omitted)
+
+### Hidden files
+- `createHiddenFile(file, parentId)` / `deleteHiddenFile(id)` / `getHiddenFile(id)`
+- `downloadHiddenFile(id)` / `getHiddenFilesByParent(parentId)` / `deleteHiddenFilesByParent(parentId)`
+
+### General
+- `updateItem(id, params)` / `createVersion(id, file, tag, extraProps?, metadata?)`
+- `getProjectData(projectId)` / `checkPermission(params)`
+
+## CLI commands
+
+```bash
+thatopen create <name> [--template bim|default|cloud|test|cloud-test]
+                                                        # Scaffold project + auto npm install
+                                                        # Use "." as name to scaffold in current directory
+thatopen serve [--port N]                                # Dev server (esbuild watch + serve bundle)
+thatopen login [--token T] [--api-url U] [--local]       # Authenticate
+thatopen publish [--name N] [--version-tag T] [--skip-build] [--app-id ID | --component-id ID]
+thatopen run [--params '{}'] [--skip-build]              # Test cloud component locally
+thatopen local-server [--port N] [--skip-build]          # Local execution server (API-compatible)
+thatopen create-tests [directory]                        # Scaffold test app + test component (cleans directory first)
+thatopen serve-tests [directory]                         # Serve test app + test component in parallel
+```
+
+## Dependencies
+
+- **Runtime**: `dotenv`, `socket.io-client`
+- **Peer** (optional): `@thatopen/components` ^3.3.1, `@thatopen/ui` ^3.3.3, `three` ^0.182.0
+- **CLI bundled**: `commander`, `jszip`

package/README.md

@@ -0,0 +1,285 @@
+# thatopen-services
+
+Client library and CLI for building BIM apps and cloud components on the [That Open Platform](https://platform.thatopen.com).
+
+## Quick Start
+
+### Create a BIM app
+
+```bash
+# Install the services package globally
+npm i thatopen-services -g
+```
+
+Then, create a brand new app repository:
+
+```bash
+npx thatopen create my-app
+cd my-app
+npm run dev
+
+# Open your project on platform.thatopen.com and click the debug button
+```
+
+You can also scaffold in the current directory:
+
+```bash
+mkdir my-app && cd my-app
+npx thatopen create .
+npm run dev
+```
+
+### Create a cloud component
+
+```bash
+npx thatopen create my-component --template cloud
+cd my-component
+npm run run   # Build and test locally
+```
+
+### Templates
+
+| Template | Command | What you get |
+|----------|---------|--------------|
+| `bim` (default) | `npx thatopen create my-app` | Three.js + BIM viewer + platform UI components |
+| `default` | `npx thatopen create my-app --template default` | Minimal app showing platform context |
+| `cloud` | `npx thatopen create my-component --template cloud` | Server-side Node.js component |
+| `test` | `npx thatopen create my-tests --template test` | Browser test app that exercises every API endpoint |
+| `cloud-test` | `npx thatopen create my-tests --template cloud-test` | Cloud component test suite for server-side API testing |
+
+Use `npx thatopen create .` to scaffold in the current directory instead of creating a new one.
+
+## What's in this package
+
+- **Library** — `EngineServicesClient` 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 UI components (AppManager, ViewportManager, etc.)
+
+## Library usage
+
+```typescript
+import { EngineServicesClient } from 'thatopen-services';
+
+const client = new EngineServicesClient(accessToken, apiUrl);
+
+// Files
+const files = await client.listFiles();
+await client.createFile({ file: blob, name: "model.ifc", versionTag: "v1" });
+const response = await client.downloadFile(fileId);
+
+// Folders
+const folders = await client.listFolders();
+await client.createFolder("My Folder");
+
+// Cloud component execution
+const { executionId } = await client.executeComponent(componentId, { param: "value" });
+client.onExecutionProgress(executionId, (data) => {
+  console.log(data.progressUpdate, data.messageUpdate);
+});
+```
+
+Inside platform apps, use the Auth0 JWT from the platform context:
+
+```typescript
+const ctx = window.__THATOPEN_CONTEXT__; // { appId, projectId, accessToken, apiUrl }
+const client = new EngineServicesClient(ctx.accessToken, ctx.apiUrl, { useBearer: true });
+```
+
+## CLI commands
+
+| Command | Description |
+|---------|-------------|
+| `thatopen create <name> [--template bim\|default\|cloud\|test\|cloud-test]` | Scaffold a new project (use `.` for current directory) |
+| `thatopen serve [--port N]` | Dev server (esbuild watch + serve bundle) |
+| `thatopen login [--token T] [--local]` | Authenticate with the platform |
+| `thatopen publish` | Build and publish to the platform |
+| `thatopen run [--params '{}']` | Build and test a cloud component locally |
+| `thatopen create-tests [directory]` | Scaffold both a test app and test cloud component |
+| `thatopen serve-tests [directory]` | Serve both the test app and test component in parallel |
+
+## App workflow
+
+Apps run inside the That Open Platform (platform.thatopen.com) within a project. They are served inside the platform's iframe — not as standalone websites.
+
+```bash
+# 1. Create project (dependencies are installed automatically)
+npx thatopen create my-app
+cd my-app
+
+# 2. Develop locally
+npm run dev
+# Open your project on the platform and click the debug button.
+# Live reload is enabled — save a file to rebuild.
+
+# 3. Authenticate
+npm run login -- --token <your-token>
+
+# 4. Publish
+npm run publish
+```
+
+## Cloud component workflow
+
+```bash
+# 1. Create project (dependencies are installed automatically)
+npx thatopen create my-component --template cloud
+cd my-component
+
+# 2. Run locally
+npm run run
+
+# 3. Pass parameters
+npx thatopen run --params '{"inputFile": "model.ifc"}'
+
+# 4. Authenticate and publish
+npm run login -- --token <your-token>
+npm run publish
+```
+
+Cloud components export an `async function main()` that runs on the server. The execution engine provides globals:
+
+| Global | Purpose |
+|--------|---------|
+| `thatOpenServices` | Authenticated `EngineServicesClient` |
+| `executionParams` | Parameters passed by the caller |
+| `executionReporter` | `{ message(msg), progress(pct) }` for live feedback |
+| `OBC` | `@thatopen/components` — BIM engine |
+| `THREE` | `three` — 3D math and geometry |
+| `fs` | Node.js filesystem |
+
+## Built-in components
+
+Platform-hosted UI components loaded at runtime:
+
+```typescript
+import { AppManager, ViewportManager } from "thatopen-services";
+
+// Register all library globals once
+client.setBuiltInGlobals({ OBC, OBF, BUI, CUI, THREE, FRAGS });
+
+// Load built-in components — globals are automatically applied
+await client.initBuiltInComponent(AppManager, components);
+await client.initBuiltInComponent(ViewportManager, components);
+
+const app = components.get(AppManager);
+const viewports = components.get(ViewportManager);
+const { element, world } = await viewports.create();
+```
+
+| Component | Purpose |
+|-----------|---------|
+| `AppManager` | App shell — CSS grid layout with sidebar for switching layouts |
+| `ViewportManager` | Factory for 3D viewports with pre-configured world |
+| `LoadModelButton` | Button + dropdown for loading IFC / Fragments files |
+| `ViewerToolbar` | Toolbar with Show/Hide/Focus/Isolate and color palette |
+| `ModelsPanel` | Panel listing loaded models with search and load button |
+| `ModelsDropdown` | Dropdown selector listing loaded models |
+| `ClassificationsList` | Hierarchical table of IFC classification data |
+| `ClashesList` | Interactive clash detection results with highlighting |
+| `ClippingsList` | Panel listing clipping planes with controls |
+| `LengthMeasuringsList` | Panel listing length measurements with totals |
+| `AreaMeasuringsList` | Panel listing area measurements with totals |
+| `ColorsPalette` | Color picker with Highlighter style swatches |
+| `HighlightersList` | Panel listing Highlighter styles with manage actions |
+| `QtoComparisonList` | Side-by-side quantity comparison for two elements |
+| `QueriesHierarchy` | Recursive multi-level query browser |
+| `CustomViewLegend` | Color legend overlay |
+| `ScreenshotAnnotator` | Modal for annotating screenshots via MarkerJS |
+
+See `src/built-in/index.ts` for full API reference with config interfaces and `@example` blocks.
+
+## Config files
+
+| File | Scope | Contains |
+|------|-------|----------|
+| `~/.thatopen/config.json` | Global | `accessToken`, `apiUrl` |
+| `.thatopen` (project root) | Per-project (gitignored) | `accessToken`, `apiUrl`, `appId` or `componentId` |
+
+The CLI checks the local `.thatopen` first, then falls back to the global config.
+
+---
+
+## Development (working on this repo)
+
+### Setup
+
+```bash
+npm install
+npm run build        # Builds both library and CLI
+```
+
+### Build commands
+
+```bash
+npm run build          # Full build (library + CLI)
+npm run build:lib      # Library only
+npm run build:cli      # CLI only
+```
+
+### Testing the CLI locally
+
+```bash
+# Link the CLI globally so `thatopen` points to this repo
+npm link
+
+# Build CLI and scaffold a test app
+npm run test:cli-build-app
+
+# Build and scaffold a test cloud component
+npm run test:cli-build-component
+
+# Run the test cloud component locally
+npm run test:cli-run-component
+```
+
+### Running the platform API test suite
+
+The test suite consists of two projects scaffolded together: a **test app** (browser-based, template `test`) and a **test cloud component** (server-side, template `cloud-test`). Both exercise every `EngineServicesClient` endpoint.
+
+```bash
+# 1. Build the CLI and scaffold both test projects into a temp/ directory
+#    (deletes temp/ first if it already exists)
+yarn test:cli-build-tests
+
+# 2. Serve both the test app and the test component's local server
+yarn test:cli-serve-tests
+```
+
+Then open your project on [platform.thatopen.com](https://platform.thatopen.com) and click the debug button. The test app will show a panel with:
+
+- **Context** — current app/project/API info
+- **Execution Config** — input fields for a deployed Component ID and the local server URL (defaults to `http://localhost:4001`)
+- **Controls** — "Run All Tests" button
+- **Results** — test results grouped by API area (Context & Auth, Folders, Files, Hidden Files, Icons, Components, Apps, Execution, Built-in Components)
+
+When execution tests run, the cloud component's output appears in the same Results section as additional groups prefixed with "Local Component:" or "Deployed Component:".
+
+### Publishing a new version
+
+Publishing is handled automatically by CI when a PR with changesets is merged to `main`.
+
+**1. Create a changeset (developer does this with their changes):**
+
+```bash
+yarn changeset
+# Pick the bump type (patch / minor / major) and write a summary
+# This creates a .changeset/<random-name>.md file — commit it with your PR
+```
+
+**2. Merge the PR to `main`:**
+
+CI will automatically:
+- Consume the changeset files
+- Bump `package.json` version and update `CHANGELOG.md`
+- Commit the version bump back to `main`
+- Build and publish to npm
+
+**Manual publishing (if CI is not available):**
+
+```bash
+yarn version           # Consume changesets, bump version
+yarn build
+yarn changeset publish
+```
+
+Keep in mind the importance of semver — don't release a major for non-breaking changes.