@thatopen/services 0.0.6 → 0.2.0

package/dist/types/files.d.ts

@@ -10,6 +10,12 @@ export type HiddenFileEntity = {
 export type CreateHiddenItemResult = {
     hiddenFileId: string;
 };
+export type CreateHiddenItemsBatchResult = {
+    results: {
+        originalName: string;
+        hiddenFileId: string;
+    }[];
+};
 export type MetadataValue = string | number | boolean | null;
 export type Metadata = Record<string, MetadataValue>;
 export declare const METADATA_LIMITS: {

package/dist/types/npm.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Read-only npm credentials for the private `@thatopen` Founders beta packages.
+ * Returned by `GET /api/npm-registry/credentials` to FOUNDING members only.
+ */
+export interface NpmCredentials {
+    /** Registry the scope is pinned to (e.g. `https://registry.npmjs.org/`). */
+    registry: string;
+    /** Package scope the token grants read access to (e.g. `@thatopen`). */
+    scope: string;
+    /** The read-only npm token. */
+    token: string;
+    /** Ready-to-write `.npmrc` file body (scope pin + auth line). */
+    npmrc: string;
+}

package/dist/vite-env.d.ts

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

package/docs/builtin/paths.json

@@ -1,8 +1,4 @@
 [
-  {
-    "path": "src/built-in/AppManager/example.ts",
-    "description": ""
-  },
   {
     "path": "src/built-in/CDEManager/example.ts",
     "description": "CDEManager — CDEManager is the central state machine for a Common Data Environment. It holds files, folders, metadata schemas, viewer groups, and user permissions, and exposes a typed state machine that all file operations — selecting, editing, uploading, viewing — route through. It has no DOM or Three.js dependencies and can run in Node, a browser, or a server-side worker wherever `@thatopen/components` is available."
@@ -48,7 +44,27 @@
     "description": ""
   },
   {
-    "path": "src/built-in/ViewportsManager/example.ts",
-    "description": ""
+    "path": "src/built-in/UIManager/src/app/example.ts",
+    "description": "top-app — Front-end developers building BIM web apps need to coordinate several async initialization steps before the UI can be shown — loading the engine, preparing fragment workers, registering loaders — and users need visible feedback on what is happening during that wait, rather than a blank screen."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/AppState/example.ts",
+    "description": "Shared reactive state with AppState — Developers building interactive BIM panels often need sibling components — a filter selector and a results table, for example — to stay in sync without a shared parent. Lifting state to a common ancestor and threading it down as props works for shallow trees but becomes unwieldy as the component tree grows."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/Contexts/example.ts",
+    "description": "Consuming platform contexts in child components — Developers building custom BIM panels need access to the 3D engine, the platform API, and the current project's metadata — but threading these objects down through props across multiple component layers forces every intermediate element to know about data it doesn't use, making trees brittle and hard to refactor."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/FloatingLayout/example.ts",
+    "description": "Floating layout — Developers building BIM coordination tools often want the 3D model to fill the entire window while control panels float above it — but standard grid layouts give every area equal standing, shrinking the viewer into one cell and leaving visible seams between it and the panels."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/Notifications/example.ts",
+    "description": "Toasts, file drop, and cross-component notifications — Developers building BIM processing UIs need to surface status updates, errors, and file-drop feedback to users from different points in the component tree — but reaching back to the app root to trigger a notification from a deeply nested component requires threading a reference through every layer in between."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/Sidebar/example.ts",
+    "description": "Sidebar navigation — Product teams building BIM apps often need multiple distinct views — a 3D model viewer, a data browser, a settings screen — but wiring a custom nav bar and managing view transitions from scratch adds complexity before any real feature work begins."
   }
 ]

package/package.json

@@ -1,100 +1,100 @@
-{
-  "name": "@thatopen/services",
-  "description": "Client library and CLI for building BIM apps and cloud components on the That Open Platform",
-  "author": "That Open Company",
-  "license": "MIT",
-  "homepage": "https://github.com/ThatOpen/engine_services#readme",
-  "bugs": {
-    "url": "https://github.com/ThatOpen/engine_services/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ThatOpen/engine_services.git"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "private": false,
-  "version": "0.0.6",
-  "main": "dist/index.cjs.js",
-  "module": "dist/index.es.js",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "thatopen": "dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "src/cli/templates",
-    "src/built-in",
-    "docs",
-    "resources"
-  ],
-  "scripts": {
-    "dev": "vite",
-    "lint": "eslint src/",
-    "build": "eslint src/ && tsc && vite build && vite build --config vite.config.cli.mts && node scripts/generate-cli-docs-paths.mjs && node scripts/generate-client-examples-paths.mjs",
-    "build:lib": "tsc && vite build",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "build:cli": "vite build --config vite.config.cli.mts",
-    "preview": "vite preview",
-    "test:ui": "vite --config test/vite.config.mts",
-    "test:cli-build-app": "npm run build:cli && node test/setup-test-app.mjs",
-    "test:cli-serve-app": "cd temp/test-app && thatopen serve",
-    "test:cli-build-component": "npm run build:cli && node test/setup-test-component.mjs",
-    "test:cli-run-component": "cd temp/test-component && thatopen run --skip-build",
-    "test:cli-serve-component": "cd temp/test-component && thatopen local-server",
-    "template:app": "cd src/cli/templates/app && npm install && cd ../../../.. && node scripts/generate-template-tsconfig.mjs",
-    "template:app:dev": "cd src/cli/templates/app && npm run dev",
-    "changeset": "changeset",
-    "version": "changeset version",
-    "prepublishOnly": "npm run build"
-  },
-  "devDependencies": {
-    "@changesets/cli": "^2.27.7",
-    "@thatopen/components": "~3.4.0",
-    "@thatopen/components-front": "~3.4.0",
-    "@thatopen/fragments": "~3.4.0",
-    "@thatopen/ui": "~3.4.0",
-    "@thatopen/ui-obc": "~3.4.0",
-    "@types/node": "^20.12.12",
-    "@types/three": "^0.182.0",
-    "commander": "^14.0.3",
-    "esbuild": "^0.27.3",
-    "eslint": "9.x",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-prettier": "^5.1.3",
-    "globals": "^15.3.0",
-    "jszip": "^3.10.1",
-    "prettier": "^3.2.5",
-    "three": "^0.182.0",
-    "tsx": "^4.16.2",
-    "typescript": "^5.2.2",
-    "typescript-eslint": "^7.10.0",
-    "vite": "^5.2.0",
-    "vite-plugin-dts": "^3.9.1",
-    "vite-plugin-eslint": "^1.8.1",
-    "vitest": "^4.1.4"
-  },
-  "dependencies": {
-    "dotenv": "^16.4.5",
-    "socket.io": "^4.8.0",
-    "socket.io-client": "^4.8.0"
-  },
-  "peerDependencies": {
-    "@thatopen/components": "~3.4.0",
-    "@thatopen/ui": "~3.4.0",
-    "three": "^0.182.0"
-  },
-  "peerDependenciesMeta": {
-    "@thatopen/components": {
-      "optional": true
-    },
-    "@thatopen/ui": {
-      "optional": true
-    },
-    "three": {
-      "optional": true
-    }
-  }
+{
+  "name": "@thatopen/services",
+  "description": "Client library and CLI for building BIM apps and cloud components on the That Open Platform",
+  "author": "That Open Company",
+  "license": "MIT",
+  "homepage": "https://github.com/ThatOpen/engine_services#readme",
+  "bugs": {
+    "url": "https://github.com/ThatOpen/engine_services/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThatOpen/engine_services.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "private": false,
+  "version": "0.2.0",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.es.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "thatopen": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src/cli/templates",
+    "src/built-in",
+    "docs",
+    "resources"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "lint": "eslint src/",
+    "build": "eslint src/ && tsc && vite build && vite build --config vite.config.cli.mts && node scripts/generate-cli-docs-paths.mjs && node scripts/generate-client-examples-paths.mjs",
+    "build:lib": "tsc && vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build:cli": "vite build --config vite.config.cli.mts",
+    "preview": "vite preview",
+    "test:ui": "vite --config test/vite.config.mts",
+    "test:cli-build-app": "npm run build:cli && node test/setup-test-app.mjs",
+    "test:cli-serve-app": "cd temp/test-app && thatopen serve",
+    "test:cli-build-component": "npm run build:cli && node test/setup-test-component.mjs",
+    "test:cli-run-component": "cd temp/test-component && thatopen run --skip-build",
+    "test:cli-serve-component": "cd temp/test-component && thatopen local-server",
+    "template:app": "cd src/cli/templates/app && npm install && cd ../../../.. && node scripts/generate-template-tsconfig.mjs",
+    "template:app:dev": "cd src/cli/templates/app && npm run dev",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.7",
+    "@thatopen/components": "~3.4.0",
+    "@thatopen/components-front": "~3.4.0",
+    "@thatopen/fragments": "~3.4.0",
+    "@thatopen/ui": "~3.4.0",
+    "@thatopen/ui-obc": "~3.4.0",
+    "@types/node": "^20.12.12",
+    "@types/three": "^0.182.0",
+    "commander": "^14.0.3",
+    "esbuild": "^0.27.3",
+    "eslint": "9.x",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "globals": "^15.3.0",
+    "jszip": "^3.10.1",
+    "prettier": "^3.2.5",
+    "three": "^0.182.0",
+    "tsx": "^4.16.2",
+    "typescript": "^5.2.2",
+    "typescript-eslint": "^7.10.0",
+    "vite": "^5.2.0",
+    "vite-plugin-dts": "^3.9.1",
+    "vite-plugin-eslint": "^1.8.1",
+    "vitest": "^4.1.4"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.5",
+    "socket.io": "^4.8.0",
+    "socket.io-client": "^4.8.0"
+  },
+  "peerDependencies": {
+    "@thatopen/components": "~3.4.0",
+    "@thatopen/ui": "~3.4.0",
+    "three": "^0.182.0"
+  },
+  "peerDependenciesMeta": {
+    "@thatopen/components": {
+      "optional": true
+    },
+    "@thatopen/ui": {
+      "optional": true
+    },
+    "three": {
+      "optional": true
+    }
+  }
 }

package/resources/AGENTS.md

@@ -16,15 +16,17 @@ Do this before answering any question or writing any code. These are compact des
 
 | What | Where |
 |---|---|
-| Platform built-ins | `docs/builtin/paths.json` |
-| Platform client API | `docs/client/paths.json` |
-| CLI commands | `docs/cli/paths.json` |
+| Platform built-ins | `node_modules/@thatopen/services/docs/builtin/paths.json` |
+| Platform client API | `node_modules/@thatopen/services/docs/client/paths.json` |
+| CLI commands | `node_modules/@thatopen/services/docs/cli/paths.json` |
 | Engine components (`OBC`, `OBF`) | `https://raw.githubusercontent.com/ThatOpen/engine_components/refs/heads/main/examples/paths.json` |
 | Fragments (`FRAGS`) | `https://raw.githubusercontent.com/ThatOpen/engine_fragment/refs/heads/main/examples/paths.json` |
 | UI components (`BUI`) | `https://raw.githubusercontent.com/ThatOpen/engine_ui-components/refs/heads/main/examples/paths.json` — **skip** entries whose path contains `packages/obc` or `bim-grid` |
 
 Once you have these, you know everything available on the platform. Only then fetch a specific example file when you need implementation details.
 
+> **Path resolution:** all `path` entries inside the local indexes (`docs/`, `src/`) are relative to the `@thatopen/services` package root — prepend `node_modules/@thatopen/services/` when reading any of those files.
+
 ---
 
 ## How to work

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

@@ -1,86 +1,86 @@
-import * as OBC from "@thatopen/components";
-import * as BUI from "@thatopen/ui";
-import appManagerDef from "./index";
-
-// ── State types ───────────────────────────────────────────────────────
-
-type Panel1State = { label: string; components: OBC.Components };
-type Panel2State = { label: string; components: OBC.Components };
-
-// ── App type ──────────────────────────────────────────────────────────
-
-interface MyApp {
-  icons: ["LOAD", "TREE", "VIEW"];
-  grid: BUI.Grid<
-    ["Split", "Viewer"],
-    [{ name: "panel1"; state: Panel1State }, { name: "panel2"; state: Panel2State }]
-  >;
-}
-
-// ── Initialise OBC & BUI ──────────────────────────────────────────────
-
-BUI.Manager.init();
-const components = new OBC.Components();
-
-const AppManager = appManagerDef.componentDefinition;
-const app = components.get(AppManager<MyApp>);
-
-// ── Define element templates ──────────────────────────────────────────
-
-const panel1Template: BUI.StatefullComponent<Panel1State> = ({ label, components }) => {
-  const app = components.get(AppManager<MyApp>);
-  return BUI.html`
-    <bim-panel active label=${label} style="min-width: 14rem;">
-      <bim-panel-section label="Actions">
-        <bim-button icon=${app.icons.LOAD} label="Load School Model"></bim-button>
-      </bim-panel-section>
-      <bim-panel-section label="Info">
-        <bim-label>Use the sidebar to switch layouts.</bim-label>
-      </bim-panel-section>
-    </bim-panel>
-  `;
-};
-
-const panel2Template: BUI.StatefullComponent<Panel2State> = ({ label, components }) => {
-  const app = components.get(AppManager<MyApp>);
-  return BUI.html`
-    <bim-panel active label=${label} style="min-width: 14rem;">
-      <bim-panel-section label="Settings">
-        <bim-button icon=${app.icons.VIEW} label="View"></bim-button>
-      </bim-panel-section>
-    </bim-panel>
-  `;
-};
-
-// ── Init ──────────────────────────────────────────────────────────────
-
-app.init({
-  icons: {
-    LOAD: "solar:upload-bold",
-    TREE: "mdi:file-tree",
-    VIEW: "mdi:monitor",
-  },
-  grid: (grid) => {
-    grid.elements = {
-      panel1: { template: panel1Template, initialState: { label: "Models", components } },
-      panel2: { template: panel2Template, initialState: { label: "Settings", components } },
-    };
-    grid.layouts = {
-      Split: {
-        template: `
-          "panel1" 1fr
-          "panel2" 1fr
-          / 25rem 1fr`,
-        icon: app.icons.TREE,
-      },
-      Viewer: {
-        template: `"panel1" 1fr / 1fr`,
-        icon: app.icons.VIEW,
-      },
-    };
-    grid.layout = "Split";
-  },
-  container: document.getElementById("container")!,
-});
-
-app.showSidebar = true;
+import * as OBC from "@thatopen/components";
+import * as BUI from "@thatopen/ui";
+import appManagerDef from "./index";
+
+// ── State types ───────────────────────────────────────────────────────
+
+type Panel1State = { label: string; components: OBC.Components };
+type Panel2State = { label: string; components: OBC.Components };
+
+// ── App type ──────────────────────────────────────────────────────────
+
+interface MyApp {
+  icons: ["LOAD", "TREE", "VIEW"];
+  grid: BUI.Grid<
+    ["Split", "Viewer"],
+    [{ name: "panel1"; state: Panel1State }, { name: "panel2"; state: Panel2State }]
+  >;
+}
+
+// ── Initialise OBC & BUI ──────────────────────────────────────────────
+
+BUI.Manager.init();
+const components = new OBC.Components();
+
+const AppManager = appManagerDef.componentDefinition;
+const app = components.get(AppManager<MyApp>);
+
+// ── Define element templates ──────────────────────────────────────────
+
+const panel1Template: BUI.StatefullComponent<Panel1State> = ({ label, components }) => {
+  const app = components.get(AppManager<MyApp>);
+  return BUI.html`
+    <bim-panel active label=${label} style="min-width: 14rem;">
+      <bim-panel-section label="Actions">
+        <bim-button icon=${app.icons.LOAD} label="Load School Model"></bim-button>
+      </bim-panel-section>
+      <bim-panel-section label="Info">
+        <bim-label>Use the sidebar to switch layouts.</bim-label>
+      </bim-panel-section>
+    </bim-panel>
+  `;
+};
+
+const panel2Template: BUI.StatefullComponent<Panel2State> = ({ label, components }) => {
+  const app = components.get(AppManager<MyApp>);
+  return BUI.html`
+    <bim-panel active label=${label} style="min-width: 14rem;">
+      <bim-panel-section label="Settings">
+        <bim-button icon=${app.icons.VIEW} label="View"></bim-button>
+      </bim-panel-section>
+    </bim-panel>
+  `;
+};
+
+// ── Init ──────────────────────────────────────────────────────────────
+
+app.init({
+  icons: {
+    LOAD: "solar:upload-bold",
+    TREE: "mdi:file-tree",
+    VIEW: "mdi:monitor",
+  },
+  grid: (grid) => {
+    grid.elements = {
+      panel1: { template: panel1Template, initialState: { label: "Models", components } },
+      panel2: { template: panel2Template, initialState: { label: "Settings", components } },
+    };
+    grid.layouts = {
+      Split: {
+        template: `
+          "panel1" 1fr
+          "panel2" 1fr
+          / 25rem 1fr`,
+        icon: app.icons.TREE,
+      },
+      Viewer: {
+        template: `"panel1" 1fr / 1fr`,
+        icon: app.icons.VIEW,
+      },
+    };
+    grid.layout = "Split";
+  },
+  container: document.getElementById("container")!,
+});
+
+app.showSidebar = true;