@thatopen/services 0.3.0 → 0.3.2

package/README.md

@@ -2,6 +2,9 @@
 
 Client library and CLI for building BIM apps and cloud components on [That Open Platform](https://platform.thatopen.com). Apps run inside the platform's browser environment; cloud components run server-side and can be triggered from any app.
 
+> **Using an AI assistant?** Point it at this single file and it can take you from nothing to a running app:
+> → [`docs/ai-quickstart.md`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/ai-quickstart.md)
+
 ## Quick Start
 
 ### 1. Install the CLI

package/dist/built-in/index.d.ts

@@ -80,8 +80,6 @@ export type CDEMachineState = {
     kind: "idle";
 } | {
     kind: "loading";
-} | {
-    kind: "uploading";
 } | {
     kind: "preparing";
     files: CDEFile[];
@@ -356,6 +354,22 @@ declare class _CDEManager extends OBC.Component implements OBC.Transitionable<CD
         files?: CDEFile[];
         folder?: ItemFolder;
     }>;
+    readonly onUploadStarted: OBC.Event<{
+        count: number;
+    }>;
+    readonly onIfcConversionStarted: OBC.Event<{
+        file: CDEFile;
+    }>;
+    readonly onIfcConversionProgress: OBC.Event<{
+        file: CDEFile;
+        progress: number;
+    }>;
+    readonly onIfcConversionCompleted: OBC.Event<{
+        file: CDEFile;
+        success: boolean;
+        error?: string;
+    }>;
+    readonly conversionProgress: Map<string, number>;
     enabled: boolean;
     projectName: string;
     missingMetadataPlaceholder: string;
@@ -363,6 +377,7 @@ declare class _CDEManager extends OBC.Component implements OBC.Transitionable<CD
     visibleColumns: Set<string>;
     ctx?: CDEContext;
     private _machineState;
+    private _activeUploads;
     private _showArchived;
     private _preArchivedViewMode;
     private _archivedFiles;
@@ -465,6 +480,11 @@ declare class _CDEManager extends OBC.Component implements OBC.Transitionable<CD
         file: CDEFile;
         existing: CDEFile;
     }[];
+    resolveViewFile(file: CDEFile): CDEFile;
+    private _saveConversionIndex;
+    private _loadConversionIndex;
+    private _resumePendingConversions;
+    private _triggerIfcConversions;
     uploadFiles(files: File[], folderId?: string | null, options?: {
         forceNew?: boolean;
     }): Promise<void>;

package/dist/cli.js

@@ -8099,13 +8099,13 @@ const createCommand = new Command2("create").argument("<project-name>", 'Name of
     console.error(`Unknown template "${opts.template}". Available: ${TEMPLATES.join(", ")}`);
     process.exit(1);
   }
-  if (template === "app" && !opts.beta) {
+  if (!opts.beta) {
     console.error(
-      `The "app" template currently requires the beta engine libraries.
+      `Non-beta projects are not available yet.
 
   thatopen create ${projectName} --beta
 
-Public (non-beta) engine support is coming with the October release.`
+The templates currently require the beta engine libraries. Public (non-beta) engine support is coming with the October release.`
     );
     process.exit(1);
   }

package/docs/ai-quickstart.md

@@ -0,0 +1,86 @@
+# That Open Platform — AI Quick Start (zero to a running app)
+
+You are an AI assistant. A user pointed you at this URL so you can scaffold and run a
+**BIM app** 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.
+
+---
+
+## 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)
+
+```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 app
+
+```bash
+thatopen create my-app --beta
+cd my-app
+```
+
+`--beta` is required for now: the bundled viewer uses engine APIs that currently live only
+in the beta libraries (public engine support lands with the October release). `create`
+configures private beta access from your platform token and runs `npm install` for you.
+
+## 4. Run it
+
+```bash
+npm run dev
+```
+
+This 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.
+
+## 5. Then build — read the in-project agent guide
+
+The scaffold is a real app, 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: it
+indexes every platform built-in, the client API, the CLI, and the engine / UI example sets.
+Load those indexes before writing code. **All UI must be built with Lit + `@thatopen/ui`
+(`BUI`)** — consult the design system before writing any UI. Run the app first, then extend
+it; don't rebuild a viewer from scratch.
+
+## 6. Publish (when ready)
+
+```bash
+npm run publish
+```
+
+Builds the app, zips it (`dist/bundle.zip`), and uploads a new version to the platform.
+
+---
+
+## 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

@@ -17,12 +17,13 @@ thatopen create .             # scaffold into the current directory
 - `--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.
+- `--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
-thatopen create my-app -t cloud-component
 thatopen create my-app --beta
+thatopen create my-app -t cloud-component --beta
 thatopen create . --beta
 ```

package/package.json

@@ -15,7 +15,7 @@
     "access": "public"
   },
   "private": false,
-  "version": "0.3.0",
+  "version": "0.3.2",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "types": "dist/index.d.ts",
@@ -67,7 +67,7 @@
     "globals": "^15.3.0",
     "jszip": "^3.10.1",
     "prettier": "^3.2.5",
-    "three": "^0.182.0",
+    "three": ">=0.182.0",
     "tsx": "^4.16.2",
     "typescript": "^5.2.2",
     "typescript-eslint": "^7.10.0",
@@ -84,7 +84,7 @@
   "peerDependencies": {
     "@thatopen/components": "~3.4.0",
     "@thatopen/ui": "~3.4.0",
-    "three": "^0.182.0"
+    "three": ">=0.182.0"
   },
   "peerDependenciesMeta": {
     "@thatopen/components": {