@thatopen/services 0.16.0 → 0.16.1

package/docs/ai-quickstart.md

@@ -51,7 +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/data → API Tokens → create → copy.**
+  → **https://platform.thatopen.com/dashboard → Account → Tokens → create → copy.**
+  (The Data overview shows the same Tokens card; both paths work.)
   Ask the user to paste it. **Never print it back, never write it into a file, never commit it.**
 
 ## 1. Install the CLI
@@ -62,8 +63,9 @@ 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/data**
-→ **API Tokens** → create → copy. Ask the user to paste it, then run:
+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
+user to paste it, then run:
 
 ```bash
 thatopen login --token <platform-token>
@@ -304,8 +306,16 @@ socket.on("channelMessage", (msg) => {
 ```
 
 A reply to your `requestId` reaches only your socket — a second tool connected
-at the same time never sees it. `{ delivered: 0 }` on the ack means no tab of
-that account's app has the channel joined: open the app first.
+at the same time never sees it. Replies arrive as a `channelMessage` with
+`type: "reply"` and your `requestId` — match on the `requestId`, not the type.
+
+`{ delivered: 0 }` on the ack means no tab of that account's app has the
+channel joined — usually the app is simply not open. Apps scaffolded before
+services 0.16.1 had one more way here: they joined the channel only at the END
+of boot, so a stalled startup request left an app that looked healthy but had
+never joined, with nothing in the console either way (0.16.1 scaffolds join
+before anything boot can stall on). With the app visibly open and still
+`delivered: 0`, **ask the user to reload the app tab and retry**.
 
 To grow the app's command surface, extend `AppCommands` in
 `src/setups/channel.ts` and handle the new command — the handler's return value

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/data → API Tokens → create → copy**, then paste it
+> **https://platform.thatopen.com/dashboard → Account → Tokens → create → copy** (the Data overview 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.16.0",
+  "version": "0.16.1",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "types": "dist/index.d.ts",
@@ -25,6 +25,7 @@
   "files": [
     "dist",
     "src/cli/templates",
+    "src/core/examples",
     "src/built-in",
     "docs",
     "resources"

package/src/cli/templates/app/src/main.ts

@@ -40,6 +40,20 @@ async function main() {
   );
   components.get(UIManager).init();
 
+  // The platform channel, pre-wired (see ./setups/channel.ts): external tools
+  // of this account (an MCP server, a CLI, a plugin) can command this app, and
+  // other open tabs of it are reachable for collaboration. Joined HERE, before
+  // any await the boot can park on (the world, project data): a stalled fetch
+  // further down must not leave the app unreachable — and silently so, since a
+  // join that is never requested also never gets to time out loudly. It only
+  // exists inside the platform iframe, so a failure is a warning, never a boot
+  // error.
+  try {
+    setupChannel(client, components);
+  } catch (error) {
+    console.warn("[channel] unavailable outside the platform:", error);
+  }
+
   // One STABLE top-viewer node, returned by reference so re-rendering top-app
   // (when we add the panels below) reuses it instead of disposing/recreating
   // its world. No <top-viewer-tools>: the bim-viewer mounts its own tabbed
@@ -97,22 +111,24 @@ async function main() {
   const projectId: string | undefined = client?.context?.projectId;
   let projectData;
   try {
-    if (projectId) projectData = await client.getProjectData(projectId);
+    // Bounded: this request carries no AbortSignal, so a stalled response
+    // parked everything below it for good (that is how the app once ended up
+    // booted but with no panels and, before the channel moved up top, deaf to
+    // external tools). Past the deadline the app boots without project data —
+    // the same degraded path the catch below already provides.
+    if (projectId) {
+      projectData = await Promise.race([
+        client.getProjectData(projectId),
+        new Promise<undefined>((resolve) => {
+          setTimeout(() => resolve(undefined), 20_000);
+        }),
+      ]);
+    }
   } catch {
     /* dev/no-project → consumers degrade gracefully */
   }
   setAppContext(client, projectData);
 
-  // The platform channel, pre-wired (see ./setups/channel.ts): external tools
-  // of this account (an MCP server, a CLI, a plugin) can command this app, and
-  // other open tabs of it are reachable for collaboration. It only exists
-  // inside the platform iframe, so a failure is a warning, never a boot error.
-  try {
-    setupChannel(client, components);
-  } catch (error) {
-    console.warn("[channel] unavailable outside the platform:", error);
-  }
-
   // Pluggable loaders for <top-models-list>. The built-in ships the lightweight
   // defaults (.frag load, IFC→fragments convert); heavy/app-specific loaders are
   // registered here so they stay OUT of the built-in's bundle. The reality-capture

package/src/core/examples/.env.example

@@ -0,0 +1,7 @@
+ACCESS_TOKEN=your-access-token-here
+API_URL=https://api.thatopen.com
+PROJECT_ID=your-project-id-here
+# Required only for permissions.ts — obtain from DevTools → Network → any /api request → Authorization header (without "Bearer ")
+JWT=
+# Required only for execution.ts — obtain from listComponents() or the platform dashboard
+COMPONENT_ID=

package/src/core/examples/apps.ts

@@ -0,0 +1,67 @@
+// description: "App lifecycle — list, get with versions, create, download bundle, and archive."
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import { EngineServicesClient } from '../client';
+
+config({ path: resolve(__dirname, '.env') });
+
+const ACCESS_TOKEN = process.env.ACCESS_TOKEN;
+const API_URL = process.env.API_URL;
+const PROJECT_ID = process.env.PROJECT_ID;
+
+if (!ACCESS_TOKEN || !API_URL) {
+  throw new Error('ACCESS_TOKEN and API_URL are required in src/core/examples/.env');
+}
+
+async function main() {
+  const client = new EngineServicesClient(ACCESS_TOKEN!, API_URL!);
+
+  // --- List ---
+  const apps = await client.listApps();
+  console.log(`\nFound ${apps.length} app(s):`);
+  for (const app of apps) {
+    console.log(`  [${app._id}] ${app.name}`);
+  }
+
+  // --- Get ---
+  if (apps.length > 0) {
+    const detail = await client.listApps({ ShowVersions: true });
+    console.log('\nFirst app detail (with versions):');
+    console.log(JSON.stringify(detail[0], null, 2));
+  }
+
+  if (!PROJECT_ID) {
+    console.log('\nSkipping create/download/archive — set PROJECT_ID in .env to run the full cycle.');
+    return;
+  }
+
+  // --- Create ---
+  // The file must be a valid ZIP produced by the thatopen CLI toolchain (`thatopen publish`).
+  // Uploading an invalid or empty ZIP causes the server to close the connection — use a real built app ZIP here.
+  // appProps is optional; omitting it uses platform defaults.
+  const bundle = new Blob([''], { type: 'application/zip' });
+  const appName = `__example-test__-${Date.now()}`;
+  const created = await client.createApp({
+    file: bundle,
+    name: appName,
+    versionTag: 'v1',
+    projectId: PROJECT_ID,
+  });
+  console.log(`\nCreated app: [${created.item._id}] ${created.item.name}`);
+
+  const appId = created.item._id;
+
+  // --- Download bundle ---
+  // downloadAppBundle extracts only the JS bundle from the ZIP — not the full archive.
+  const bundleResponse = await client.downloadAppBundle(appId);
+  const bundleText = await bundleResponse.text();
+  console.log(`\nDownloaded bundle (latest): ${bundleText.slice(0, 80)}...`);
+
+  // --- Archive ---
+  // archiveApp is a soft-delete. Unlike files and components, there is no recoverApp method —
+  // archived apps can only be managed via the platform UI.
+  await client.archiveApp(appId);
+  console.log(`\nArchived app [${appId}] — account is clean.`);
+}
+
+main().catch(console.error);

package/src/core/examples/batch-reads.ts

@@ -0,0 +1,99 @@
+// description: "Batch reads — sign many hidden files, list versions and metadata for many files, and resolve many folders in one request each."
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import { EngineServicesClient } from '../client';
+
+config({ path: resolve(__dirname, '.env') });
+
+const ACCESS_TOKEN = process.env.ACCESS_TOKEN;
+const API_URL = process.env.API_URL;
+const PROJECT_ID = process.env.PROJECT_ID;
+
+if (!ACCESS_TOKEN || !API_URL) {
+  throw new Error('ACCESS_TOKEN and API_URL are required in src/core/examples/.env');
+}
+
+async function main() {
+  const client = new EngineServicesClient(ACCESS_TOKEN!, API_URL!);
+
+  if (!PROJECT_ID) {
+    console.log('Set PROJECT_ID in .env to run this example.');
+    return;
+  }
+
+  const files = await client.listFiles({ projectId: PROJECT_ID });
+  if (!files.length) {
+    console.log('No files in this project — nothing to batch.');
+    return;
+  }
+  const fileIds = files.map((file) => String(file._id));
+
+  // --- Versions for a whole page of files ---
+  // One request instead of one per file. Entries come back in request order,
+  // and a file the token cannot read carries an `error` instead of `versions`.
+  const versionEntries = await client.listVersionsBatch(fileIds);
+  console.log('\nVersions per file:');
+  for (const entry of versionEntries) {
+    if (entry.error) {
+      console.log(`  ${entry.itemId} → ${entry.error.status} ${entry.error.message}`);
+      continue;
+    }
+    console.log(`  ${entry.itemId} → ${entry.versions?.length ?? 0} version(s)`);
+  }
+
+  // --- Metadata for specific (file, version) pairs ---
+  // The versions above already carry their metadata, so this is only needed
+  // when the version list itself is not wanted.
+  const pairs = versionEntries
+    .filter((entry) => entry.versions?.length)
+    .map((entry) => ({
+      itemId: entry.itemId,
+      versionTag: entry.versions![0].tag,
+    }));
+  const metadataEntries = await client.getFileVersionMetadataBatch(pairs);
+  console.log('\nLatest-version metadata:');
+  for (const entry of metadataEntries) {
+    console.log(
+      `  ${entry.itemId}@${entry.versionTag} → ${JSON.stringify(entry.metadata ?? entry.error)}`,
+    );
+  }
+
+  // --- Folders by id ---
+  // Use listFolders({ projectId }) for the whole tree; this is for a known set
+  // of ids, such as the parents behind a breadcrumb.
+  const folderIds = [
+    ...new Set(files.map((file) => file.folderId).filter(Boolean).map(String)),
+  ];
+  if (folderIds.length) {
+    const folderEntries = await client.getFoldersBatch(folderIds);
+    console.log('\nFolders:');
+    for (const entry of folderEntries) {
+      console.log(`  ${entry.folderId} → ${entry.folder?.name ?? entry.error?.message}`);
+    }
+  }
+
+  // --- Signed URLs for many hidden files ---
+  // This is the call tile-based viewers (splats, point clouds) should use.
+  // Minting one URL per tile as the camera moves is what pushes a single
+  // session past the rate limit; one request covers up to 100 tiles, and
+  // longer lists are split into several requests automatically.
+  const hiddenFiles = await client.getHiddenFilesByParent(fileIds[0]);
+  if (!hiddenFiles.length) {
+    console.log('\nNo hidden files on the first file — skipping signed URLs.');
+    return;
+  }
+  const signedEntries = await client.getHiddenFileSignedUrlsBatch(
+    hiddenFiles.map((hiddenFile) => String(hiddenFile._id)),
+    3600,
+  );
+  console.log('\nSigned hidden file URLs:');
+  for (const entry of signedEntries) {
+    if (entry.error) {
+      console.log(`  ${entry.hiddenFileId} → ${entry.error.status} ${entry.error.message}`);
+      continue;
+    }
+    console.log(`  ${entry.hiddenFileId} → expires ${entry.expiresAt}`);
+  }
+}
+
+main().catch(console.error);

package/src/core/examples/channel.ts

@@ -0,0 +1,65 @@
+// description: "Platform channel (app-side, runs inside the platform iframe) — a collaboration room with presence, and typed commands from external tools (MCP, CLI, Revit, etc) with automatic replies."
+import { PlatformClient } from '../platform-client';
+
+// Unlike the other examples this is not a Node script: `client.channel` only
+// exists inside an app running in the platform's iframe, and throws anywhere
+// else. Copy `setupChannel` into your app.
+
+// The contract with an external tool, written once. Each command names its
+// payload and, if the caller waits for an answer, its reply. Use `type`, and
+// list only what the app handles.
+type McpCommands = {
+  'select-by-category': {
+    payload: { category: string };
+    reply: { count: number };
+  };
+  'get-loaded-models': { payload: undefined; reply: { models: string[] } };
+};
+
+// What tabs of this app send each other. No replies: these are events.
+type CollabEvents = {
+  'cursor-position': { userName: string; x: number; y: number; z: number };
+};
+
+export async function setupChannel(client: PlatformClient) {
+  // Commands from this account's MCP server only. `external()` with no kind
+  // hears every kind of external tool (MCP, CLI, Revit plugin, etc...).
+  const mcp = client.channel.external<McpCommands>('mcp');
+
+  // What you return is sent back to whoever asked. Throw and it gets an error
+  // instead of waiting for a timeout. A command that was sent without waiting
+  // for an answer (a notification) has its return value ignored.
+  mcp.on('select-by-category', async ({ category }) => {
+    const count = await selectByCategory(category);
+    return { count };
+  });
+  mcp.on('get-loaded-models', () => ({ models: listModels() }));
+
+  // Joining is opt-in. Nothing reaches this app until it joins, so wire it to
+  // a button, or join at startup if the app should always listen.
+  await mcp.join();
+
+  // Collaboration: other users' tabs of this same app, across accounts.
+  const collab = client.channel.collab<CollabEvents>();
+  collab.on('cursor-position', (cursor, { from }) => moveAvatar(from, cursor));
+  // `from` identifies a tab, so a departure removes exactly its avatar.
+  collab.onPeerLeft(({ from }) => removeAvatar(from));
+  await collab.join();
+
+  // Sending does nothing until the platform has confirmed the join.
+  collab.send('cursor-position', { userName: 'Ada', x: 0, y: 0, z: 0 });
+
+  // Being in a room says this tab is listening, not that anyone is there.
+  // `peers` is who the platform reports on the other end right now.
+  mcp.onChange(() => {
+    console.log(`MCP: ${mcp.joined ? 'listening' : 'off'}, ${mcp.peers.length} connected`);
+  });
+
+  return { mcp, collab };
+}
+
+// Stand-ins for the app's own logic.
+declare function selectByCategory(category: string): Promise<number>;
+declare function listModels(): string[];
+declare function moveAvatar(id: string, cursor: unknown): void;
+declare function removeAvatar(id: string): void;

package/src/core/examples/components.ts

@@ -0,0 +1,91 @@
+// description: "Cloud component lifecycle — list, get with versions, create, update, download bundle, archive, and recover."
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import { EngineServicesClient } from '../client';
+
+config({ path: resolve(__dirname, '.env') });
+
+const ACCESS_TOKEN = process.env.ACCESS_TOKEN;
+const API_URL = process.env.API_URL;
+const PROJECT_ID = process.env.PROJECT_ID;
+
+if (!ACCESS_TOKEN || !API_URL) {
+  throw new Error('ACCESS_TOKEN and API_URL are required in src/core/examples/.env');
+}
+
+async function main() {
+  const client = new EngineServicesClient(ACCESS_TOKEN!, API_URL!);
+
+  // --- List ---
+  const components = await client.listComponents();
+  console.log(`\nFound ${components.length} component(s):`);
+  for (const c of components) {
+    console.log(`  [${c._id}] ${c.name}`);
+  }
+
+  // --- Get ---
+  if (components.length > 0) {
+    const detail = await client.getComponent(components[0]._id, { showVersions: true });
+    console.log('\nFirst component detail (with versions):');
+    console.log(JSON.stringify(detail, null, 2));
+  }
+
+  if (!PROJECT_ID) {
+    console.log('\nSkipping create/update/download/archive — set PROJECT_ID in .env to run the full cycle.');
+    return;
+  }
+
+  // --- Create ---
+  // componentProps is required for TOOL items — the backend rejects creation without it.
+  // The file must be a valid ZIP produced by the thatopen CLI toolchain (`thatopen publish`).
+  // Uploading a raw JS blob returns 422 — use a real built component ZIP here.
+  const bundle = new Blob(['export async function main() { return { type: "SUCCESS", message: "ok" }; }'], { type: 'application/javascript' });
+  const componentName = `__example-test__-${Date.now()}`;
+  const created = await client.createComponent({
+    file: bundle,
+    name: componentName,
+    versionTag: 'v1',
+    projectId: PROJECT_ID,
+    componentProps: { type: 'CLOUD', tier: 'FREE', isPublic: false },
+  });
+  console.log(`\nCreated component: [${created.item._id}] ${created.item.name}`);
+
+  const componentId = created.item._id;
+
+  // --- Update (rename) ---
+  const renamed = await client.updateComponent(componentId, { name: `${componentName}-renamed` });
+  console.log(`\nRenamed to: ${renamed.item?.name}`);
+
+  // --- Update (new version) ---
+  const bundleV2 = new Blob(['export async function main() { return { type: "SUCCESS", message: "v2" }; }'], { type: 'application/javascript' });
+  const versioned = await client.updateComponent(componentId, {
+    file: bundleV2,
+    versionTag: 'v2',
+    componentProps: { type: 'CLOUD', tier: 'FREE', isPublic: false },
+  });
+  console.log(`\nUploaded new version: ${versioned.version?.tag}`);
+
+  // --- Download bundle ---
+  // downloadComponentBundle extracts only the JS bundle from the ZIP — not the full archive.
+  const bundleResponse = await client.downloadComponentBundle(componentId);
+  const bundleText = await bundleResponse.text();
+  console.log(`\nDownloaded bundle (latest): ${bundleText.slice(0, 80)}...`);
+
+  const bundleV1Response = await client.downloadComponentBundle(componentId, { versionTag: 'v1' });
+  const bundleV1Text = await bundleV1Response.text();
+  console.log(`Downloaded bundle (v1): ${bundleV1Text.slice(0, 80)}...`);
+
+  // --- Archive / Recover ---
+  // archiveComponent is a soft-delete — recoverable with recoverComponent.
+  await client.archiveComponent(componentId);
+  console.log(`\nArchived component [${componentId}]`);
+
+  await client.recoverComponent(componentId);
+  console.log('Recovered component.');
+
+  // Archive again to clean up.
+  await client.archiveComponent(componentId);
+  console.log(`Re-archived component — account is clean.`);
+}
+
+main().catch(console.error);

package/src/core/examples/execution.ts

@@ -0,0 +1,75 @@
+// description: "Cloud component execution — trigger, track progress via WebSocket, list, get, and abort executions."
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import { EngineServicesClient } from '../client';
+
+config({ path: resolve(__dirname, '.env') });
+
+const ACCESS_TOKEN = process.env.ACCESS_TOKEN;
+const API_URL = process.env.API_URL;
+const PROJECT_ID = process.env.PROJECT_ID;
+
+// Required: a published cloud component ID.
+// Obtain it from `listComponents()` or from the platform dashboard.
+// Set it as COMPONENT_ID in src/core/examples/.env.
+const COMPONENT_ID = process.env.COMPONENT_ID;
+
+if (!ACCESS_TOKEN || !API_URL) {
+  throw new Error('ACCESS_TOKEN and API_URL are required in src/core/examples/.env');
+}
+
+if (!COMPONENT_ID) {
+  throw new Error(
+    'COMPONENT_ID is required to run execution.ts.\n' +
+    'Get it from `npx tsx src/core/examples/components.ts` once you have a published component,\n' +
+    'or from the platform dashboard. Set it as COMPONENT_ID in src/core/examples/.env.',
+  );
+}
+
+async function main() {
+  const client = new EngineServicesClient(ACCESS_TOKEN!, API_URL!);
+
+  // --- Execute ---
+  // Pass projectId in executionParams to scope the execution to a project.
+  // The backend validates that the component is linked to that project — a foreign projectId returns 403.
+  // Omit projectId for personal (ownership) executions.
+  const { executionId } = await client.executeComponent(
+    COMPONENT_ID!,
+    { ...(PROJECT_ID && { projectId: PROJECT_ID }) },
+  );
+  console.log(`\nStarted execution: [${executionId}]`);
+
+  // --- Track progress via WebSocket ---
+  // onExecutionProgress fires on each progress event until the execution completes.
+  // The socket is not automatically closed — the callback receives a final event when done.
+  await new Promise<void>((resolve) => {
+    client.onExecutionProgress(executionId, (data) => {
+      if (data.progressUpdate) {
+        console.log(`  progress: ${data.progressUpdate.progress}%`);
+        if (data.progressUpdate.result) {
+          console.log(`  result: ${data.progressUpdate.result}`, data.progressUpdate.resultMessage ?? '');
+          resolve();
+        }
+      }
+      if (data.messageUpdate) {
+        console.log(`  message: ${data.messageUpdate.content}`);
+      }
+    });
+  });
+
+  // --- Get execution detail ---
+  const execution = await client.getExecution(executionId);
+  console.log('\nExecution detail:');
+  console.log(JSON.stringify(execution, null, 2));
+
+  // --- List executions for the component ---
+  const executions = await client.listExecutions(COMPONENT_ID!);
+  console.log(`\nTotal executions for component: ${executions.length}`);
+
+  // --- Abort (demonstrates the API — only useful on long-running executions) ---
+  // abortExecution on an already-completed execution is a no-op on most backends.
+  // In production, call it before the WebSocket resolves to cancel a running execution.
+  console.log('\n(Skipping abortExecution — execution already completed.)');
+}
+
+main().catch(console.error);

package/src/core/examples/file-metadata.ts

@@ -0,0 +1,94 @@
+// description: "File metadata and versioning — get, update, and delete per-version metadata; list, archive, recover, and permanently delete versions."
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import { EngineServicesClient } from '../client';
+
+config({ path: resolve(__dirname, '.env') });
+
+const ACCESS_TOKEN = process.env.ACCESS_TOKEN;
+const API_URL = process.env.API_URL;
+const PROJECT_ID = process.env.PROJECT_ID;
+
+if (!ACCESS_TOKEN || !API_URL) {
+  throw new Error('ACCESS_TOKEN and API_URL are required in src/core/examples/.env');
+}
+
+async function main() {
+  const client = new EngineServicesClient(ACCESS_TOKEN!, API_URL!);
+
+  if (!PROJECT_ID) {
+    console.log('Set PROJECT_ID in .env to run this example.');
+    return;
+  }
+
+  // Create a test file to work with.
+  const blob = new Blob([JSON.stringify({ test: true })], { type: 'application/json' });
+  const fileName = `__example-test__-${Date.now()}.json`;
+  const created = await client.createFile({ file: blob, name: fileName, versionTag: 'v1', projectId: PROJECT_ID });
+  const fileId = created.item._id;
+  console.log(`\nCreated test file: [${fileId}] ${created.item.name}`);
+
+  // --- Get metadata (empty on a fresh version) ---
+  // Returns {} when the version exists but has no metadata yet — not null or 404.
+  const empty = await client.getFileVersionMetadata(fileId, 'v1');
+  console.log(`\nMetadata on v1 (fresh): ${JSON.stringify(empty)}`);
+
+  // --- Update metadata ---
+  const updated = await client.updateFileVersionMetadata(fileId, 'v1', {
+    discipline: 'structural',
+    approved: 'true',
+  });
+  console.log(`\nUpdated metadata: ${JSON.stringify(updated)}`);
+
+  // --- Get metadata (after update) ---
+  const meta = await client.getFileVersionMetadata(fileId, 'v1');
+  console.log(`\nMetadata on v1 (after update): ${JSON.stringify(meta)}`);
+
+  // --- Upload a second version and set metadata on it ---
+  const blobV2 = new Blob([JSON.stringify({ test: true, version: 2 })], { type: 'application/json' });
+  await client.updateFile(fileId, { file: blobV2, versionTag: 'v2' });
+  await client.updateFileVersionMetadata(fileId, 'v2', { discipline: 'architecture' });
+  console.log('\nUploaded v2 with its own metadata.');
+
+  // Metadata is per-version — each version holds its own independent metadata object.
+  const metaV1 = await client.getFileVersionMetadata(fileId, 'v1');
+  const metaV2 = await client.getFileVersionMetadata(fileId, 'v2');
+  console.log(`\nv1 metadata: ${JSON.stringify(metaV1)}`);
+  console.log(`v2 metadata: ${JSON.stringify(metaV2)}`);
+
+  // --- List versions ---
+  const versions = await client.listVersions(fileId);
+  console.log(`\nVersions (${versions.length}):`);
+  for (const v of versions) {
+    console.log(`  [${v.tag}] created: ${v.createdAt}`);
+  }
+
+  // --- Archive a version ---
+  // A version must be archived before it can be permanently deleted.
+  await client.archiveVersion(fileId, 'v1');
+  console.log('\nArchived v1.');
+
+  const versionsAfterArchive = await client.listVersions(fileId, { archived: false });
+  console.log(`Active versions after archiving v1: ${versionsAfterArchive.map(v => v.tag).join(', ')}`);
+
+  // --- Recover a version ---
+  await client.recoverVersion(fileId, 'v1');
+  console.log('Recovered v1.');
+
+  // --- Delete metadata ---
+  await client.deleteFileVersionMetadata(fileId, 'v1');
+  const afterDelete = await client.getFileVersionMetadata(fileId, 'v1');
+  console.log(`\nMetadata on v1 after delete: ${JSON.stringify(afterDelete)}`);
+
+  // --- Delete a version permanently ---
+  // archiveVersion first is required — deleteVersion on an active version returns an error.
+  await client.archiveVersion(fileId, 'v1');
+  await client.deleteVersion(fileId, 'v1');
+  console.log('\nPermanently deleted v1.');
+
+  // --- Cleanup ---
+  await client.archiveFile(fileId);
+  console.log(`\nArchived test file [${fileId}] — account is clean.`);
+}
+
+main().catch(console.error);

package/src/core/examples/files.ts

@@ -0,0 +1,81 @@
+// description: "File lifecycle — list, get with versions, create, rename, upload new version, download by version, archive, and recover."
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import { EngineServicesClient } from '../client';
+
+config({ path: resolve(__dirname, '.env') });
+
+const ACCESS_TOKEN = process.env.ACCESS_TOKEN;
+const API_URL = process.env.API_URL;
+const PROJECT_ID = process.env.PROJECT_ID;
+
+if (!ACCESS_TOKEN || !API_URL) {
+  throw new Error('ACCESS_TOKEN and API_URL are required in src/core/examples/.env');
+}
+
+async function main() {
+  const client = new EngineServicesClient(ACCESS_TOKEN!, API_URL!);
+
+  // --- List ---
+  const files = await client.listFiles();
+  console.log(`\nFound ${files.length} file(s):`);
+  for (const file of files) {
+    console.log(`  [${file._id}] ${file.name}`);
+  }
+
+  // --- Get ---
+  if (files.length > 0) {
+    const detail = await client.getFile(files[0]._id, { showVersions: true });
+    console.log('\nFirst file detail (with versions):');
+    console.log(JSON.stringify(detail, null, 2));
+  }
+
+  if (!PROJECT_ID) {
+    console.log('\nSkipping create/update/download/archive — set PROJECT_ID in .env to run the full cycle.');
+    return;
+  }
+
+  // --- Create ---
+  // projectId is required — the backend rejects uploads without one.
+  const fileName = `__example-test__-${Date.now()}.json`;
+  const blob = new Blob([JSON.stringify({ test: true })], { type: 'application/json' });
+  const created = await client.createFile({ file: blob, name: fileName, versionTag: 'v1', projectId: PROJECT_ID });
+  console.log(`\nCreated file: [${created.item._id}] ${created.item.name}`);
+
+  const fileId = created.item._id;
+
+  // --- Update (rename) ---
+  const renamed = await client.updateFile(fileId, { name: `${fileName}-renamed` });
+  console.log(`\nRenamed to: ${renamed.item?.name}`);
+
+  // --- Update (new version) ---
+  const blobV2 = new Blob([JSON.stringify({ test: true, version: 2 })], { type: 'application/json' });
+  const versioned = await client.updateFile(fileId, { file: blobV2, versionTag: 'v2' });
+  console.log(`\nUploaded new version: ${versioned.version?.tag}`);
+
+  // --- Download ---
+  // Without versionTag, always downloads the latest version — not necessarily the one from createFile.
+  const response = await client.downloadFile(fileId);
+  const text = await response.text();
+  console.log(`\nDownloaded content (latest version): ${text}`);
+
+  const responseV1 = await client.downloadFile(fileId, { versionTag: 'v1' });
+  const textV1 = await responseV1.text();
+  console.log(`Downloaded content (v1): ${textV1}`);
+
+  // --- Archive / Recover ---
+  // archiveFile is a soft-delete — the file can be recovered with recoverFile.
+  await client.archiveFile(fileId);
+  console.log(`\nArchived file [${fileId}]`);
+
+  // recoverFile returns no body — confirm by re-fetching the file.
+  await client.recoverFile(fileId);
+  const recovered = await client.getFile(fileId);
+  console.log(`Recovered file: ${recovered.name}`);
+
+  // Archive again to leave the account clean.
+  await client.archiveFile(fileId);
+  console.log(`Re-archived test file [${fileId}] — account is clean.`);
+}
+
+main().catch(console.error);

package/src/core/examples/folders.ts

@@ -0,0 +1,82 @@
+// description: "Folder lifecycle — list, get, create nested folders, list files inside a folder, rename, download as ZIP, archive, and recover."
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import { EngineServicesClient } from '../client';
+
+config({ path: resolve(__dirname, '.env') });
+
+const ACCESS_TOKEN = process.env.ACCESS_TOKEN;
+const API_URL = process.env.API_URL;
+const PROJECT_ID = process.env.PROJECT_ID;
+
+if (!ACCESS_TOKEN || !API_URL) {
+  throw new Error('ACCESS_TOKEN and API_URL are required in src/core/examples/.env');
+}
+
+async function main() {
+  const client = new EngineServicesClient(ACCESS_TOKEN!, API_URL!);
+
+  // --- List ---
+  const folders = await client.listFolders();
+  console.log(`\nFound ${folders.length} folder(s):`);
+  for (const folder of folders) {
+    console.log(`  [${folder._id}] ${folder.name}`);
+  }
+
+  // --- Get ---
+  if (folders.length > 0) {
+    const detail = await client.getFolder(folders[0]._id);
+    console.log('\nFirst folder detail:');
+    console.log(JSON.stringify(detail, null, 2));
+  }
+
+  if (!PROJECT_ID) {
+    console.log('\nSkipping create/update/download/archive — set PROJECT_ID in .env to run the full cycle.');
+    return;
+  }
+
+  // --- Create (parent) ---
+  const folderName = `__example-test__-${Date.now()}`;
+  const parent = await client.createFolder(folderName, undefined, PROJECT_ID);
+  console.log(`\nCreated folder: [${parent._id}] ${parent.name}`);
+
+  // --- Create (nested) ---
+  // parentId nests the folder inside another — omitting it creates a root-level folder.
+  const child = await client.createFolder(`${folderName}-child`, parent._id, PROJECT_ID);
+  console.log(`Created nested folder: [${child._id}] ${child.name}`);
+
+  // --- List by parent ---
+  // NOTE: listFolders({ parentFolderId }) returned 0 even after creating a child with that parentId.
+  // The backend may not index parentFolderId for filtering, or the field name differs internally.
+  const children = await client.listFolders({ parentFolderId: parent._id });
+  console.log(`\nChildren of [${parent._id}]: ${children.length} folder(s)`);
+
+  // --- List files inside a folder ---
+  const filesInFolder = await client.listFiles({ folderId: parent._id });
+  console.log(`Files inside folder: ${filesInFolder.length}`);
+
+  // --- Update (rename) ---
+  const renamed = await client.updateFolder(parent._id, { name: `${folderName}-renamed` });
+  console.log(`\nRenamed to: ${renamed.name}`);
+
+  // --- Download as ZIP ---
+  const zip = await client.downloadFolder(parent._id);
+  const buffer = await zip.arrayBuffer();
+  console.log(`\nDownloaded folder ZIP: ${buffer.byteLength} bytes`);
+
+  // --- Archive / Recover ---
+  // archiveFolder is a soft-delete — recoverable with recoverFolder.
+  // Archiving a parent cascades to all children: sub-folders and their files are archived too.
+  await client.archiveFolder(child._id);
+  console.log(`\nArchived child folder [${child._id}]`);
+
+  await client.recoverFolder(child._id);
+  console.log(`Recovered child folder [${child._id}]`);
+
+  // Archive both to clean up.
+  await client.archiveFolder(child._id);
+  await client.archiveFolder(parent._id);
+  console.log(`Re-archived folders — account is clean.`);
+}
+
+main().catch(console.error);

package/src/core/examples/hidden-files.ts

@@ -0,0 +1,81 @@
+// description: "Hidden file lifecycle — create, get, list by parent, download, and delete."
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import { EngineServicesClient } from '../client';
+
+config({ path: resolve(__dirname, '.env') });
+
+const ACCESS_TOKEN = process.env.ACCESS_TOKEN;
+const API_URL = process.env.API_URL;
+const PROJECT_ID = process.env.PROJECT_ID;
+
+if (!ACCESS_TOKEN || !API_URL) {
+  throw new Error('ACCESS_TOKEN and API_URL are required in src/core/examples/.env');
+}
+
+async function main() {
+  const client = new EngineServicesClient(ACCESS_TOKEN!, API_URL!);
+
+  if (!PROJECT_ID) {
+    console.log('Set PROJECT_ID in .env to run this example.');
+    return;
+  }
+
+  // Hidden files are always attached to a parent item — they have no standalone existence.
+  // Create a parent file to work with.
+  const parentBlob = new Blob([JSON.stringify({ test: true })], { type: 'application/json' });
+  const parentName = `__example-test__-${Date.now()}.json`;
+  const parent = await client.createFile({ file: parentBlob, name: parentName, versionTag: 'v1', projectId: PROJECT_ID });
+  const parentId = parent.item._id;
+  console.log(`\nCreated parent file: [${parentId}] ${parent.item.name}`);
+
+  // --- Create hidden files ---
+  const hiddenBlob1 = new Blob([JSON.stringify({ hidden: 1 })], { type: 'application/json' });
+  const hiddenBlob2 = new Blob([JSON.stringify({ hidden: 2 })], { type: 'application/json' });
+
+  const hidden1 = await client.createHiddenFile(hiddenBlob1, parentId);
+  console.log(`\nCreated hidden file 1: [${hidden1.hiddenFileId}]`);
+
+  const hidden2 = await client.createHiddenFile(hiddenBlob2, parentId);
+  console.log(`Created hidden file 2: [${hidden2.hiddenFileId}]`);
+
+  // --- Get ---
+  const fetched = await client.getHiddenFile(hidden1.hiddenFileId);
+  console.log(`\nHidden file 1 detail:`);
+  console.log(JSON.stringify(fetched, null, 2));
+
+  // --- List by parent ---
+  const allHidden = await client.getHiddenFilesByParent(parentId);
+  console.log(`\nHidden files attached to parent: ${allHidden.length}`);
+  for (const h of allHidden) {
+    console.log(`  [${h._id}]`);
+  }
+
+  // --- Download ---
+  const response = await client.downloadHiddenFile(hidden1.hiddenFileId);
+  const text = await response.text();
+  console.log(`\nDownloaded hidden file 1: ${text}`);
+
+  // --- Delete one ---
+  await client.deleteHiddenFile(hidden1.hiddenFileId);
+  console.log(`\nDeleted hidden file 1 [${hidden1.hiddenFileId}]`);
+
+  // NOTE: getHiddenFilesByParent may still return deleted files immediately after deletion —
+  // the backend list appears to be eventually consistent.
+  const afterDelete = await client.getHiddenFilesByParent(parentId);
+  console.log(`Hidden files remaining: ${afterDelete.length}`);
+
+  // --- Delete all by parent ---
+  // deleteHiddenFilesByParent removes all hidden files attached to the parent in one call.
+  await client.deleteHiddenFilesByParent(parentId);
+  console.log(`\nDeleted all remaining hidden files for parent [${parentId}]`);
+
+  const afterDeleteAll = await client.getHiddenFilesByParent(parentId);
+  console.log(`Hidden files remaining: ${afterDeleteAll.length}`);
+
+  // --- Cleanup ---
+  await client.archiveFile(parentId);
+  console.log(`\nArchived parent file [${parentId}] — account is clean.`);
+}
+
+main().catch(console.error);

package/src/core/examples/icons.ts

@@ -0,0 +1,68 @@
+// description: "Item icon management — upload, download, and remove icons on any item (file, app, or component)."
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import { EngineServicesClient } from '../client';
+
+config({ path: resolve(__dirname, '.env') });
+
+const ACCESS_TOKEN = process.env.ACCESS_TOKEN;
+const API_URL = process.env.API_URL;
+const PROJECT_ID = process.env.PROJECT_ID;
+
+if (!ACCESS_TOKEN || !API_URL) {
+  throw new Error('ACCESS_TOKEN and API_URL are required in src/core/examples/.env');
+}
+
+async function main() {
+  const client = new EngineServicesClient(ACCESS_TOKEN!, API_URL!);
+
+  if (!PROJECT_ID) {
+    console.log('Set PROJECT_ID in .env to run this example.');
+    return;
+  }
+
+  // Create a test file to attach an icon to.
+  const blob = new Blob([JSON.stringify({ test: true })], { type: 'application/json' });
+  const fileName = `__example-test__-${Date.now()}.json`;
+  const created = await client.createFile({ file: blob, name: fileName, versionTag: 'v1', projectId: PROJECT_ID });
+  const itemId = created.item._id;
+  console.log(`\nCreated test file: [${itemId}] ${created.item.name}`);
+
+  // --- Upload icon ---
+  // Accepted formats: PNG, WebP, or ICO — max 512 KB.
+  // uploadItemIcon replaces any existing icon; there is no separate "update icon" method.
+  const iconPng = generateMinimalPng();
+  const updated = await client.uploadItemIcon(itemId, iconPng);
+  console.log(`\nUploaded icon. iconFileId: ${updated.iconFileId}, mimeType: ${updated.iconMimeType}`);
+
+  // --- Download icon ---
+  const iconResponse = await client.getItemIcon(itemId);
+  const iconBuffer = await iconResponse.arrayBuffer();
+  console.log(`\nDownloaded icon: ${iconBuffer.byteLength} bytes`);
+
+  // --- Remove icon ---
+  const removed = await client.removeItemIcon(itemId);
+  console.log(`\nRemoved icon. iconFileId: ${removed.iconFileId ?? 'null'}`);
+
+  // --- Cleanup ---
+  await client.archiveFile(itemId);
+  console.log(`\nArchived test file [${itemId}] — account is clean.`);
+}
+
+// Generates the smallest valid PNG (1x1 transparent pixel) as a Blob.
+function generateMinimalPng(): Blob {
+  const bytes = new Uint8Array([
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, // PNG signature
+    0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52, // IHDR chunk length + type
+    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, // width=1, height=1
+    0x08, 0x06, 0x00, 0x00, 0x00, 0x1f, 0x15, 0xc4, // bit depth=8, colorType=6 (RGBA)
+    0x89, 0x00, 0x00, 0x00, 0x0b, 0x49, 0x44, 0x41, // IHDR CRC + IDAT chunk
+    0x54, 0x78, 0x9c, 0x62, 0x00, 0x00, 0x00, 0x02, // IDAT data (zlib compressed)
+    0x00, 0x01, 0xe2, 0x21, 0xbc, 0x33, 0x00, 0x00, // IDAT CRC
+    0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae, 0x42, // IEND chunk
+    0x60, 0x82,
+  ]);
+  return new Blob([bytes], { type: 'image/png' });
+}
+
+main().catch(console.error);

package/src/core/examples/permissions.ts

@@ -0,0 +1,87 @@
+// description: "Permission checks — single and batch permission verification using PlatformClient (requires user JWT, not API token)."
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import { PlatformClient } from '../platform-client';
+
+config({ path: resolve(__dirname, '.env') });
+
+const API_URL = process.env.API_URL;
+const PROJECT_ID = process.env.PROJECT_ID;
+
+// PlatformClient requires a user JWT — not the API token used by EngineServicesClient.
+// To run this example:
+//   1. Open the platform in your browser and log in.
+//   2. Open DevTools → Network → click any /api request.
+//   3. Copy the Authorization header value (without the "Bearer " prefix).
+//   4. Set it as JWT in src/core/examples/.env.
+const JWT = process.env.JWT;
+
+if (!API_URL) {
+  throw new Error('API_URL is required in src/core/examples/.env');
+}
+
+if (!JWT) {
+  throw new Error(
+    'JWT is required to run permissions.ts.\n' +
+    'Get it from DevTools → Network → any /api request → Authorization header (without "Bearer ").\n' +
+    'Set it as JWT in src/core/examples/.env.',
+  );
+}
+
+if (!PROJECT_ID) {
+  throw new Error('PROJECT_ID is required in src/core/examples/.env');
+}
+
+async function main() {
+  // PlatformClient extends EngineServicesClient and forces useBearer: true.
+  // It owns the JWT-only routes — checkPermission, checkPermissionBatch, getProject, getProjectData.
+  // These routes are guarded server-side and are not reachable with an API token.
+  const client = new PlatformClient(JWT!, API_URL!);
+
+  // --- Single permission check ---
+  const result = await client.checkPermission({
+    resourceType: 'STORAGE',
+    action: 'READ',
+    projectId: PROJECT_ID,
+  });
+  console.log('\nSTORAGE:READ check:');
+  console.log(`  hasPermission: ${result.hasPermission}`);
+  // scope indicates HOW the permission was granted:
+  //   'global'  — admin/owner bypass
+  //   'project' — role-level grant on the project
+  //   'entity'  — per-entity override
+  //   'none'    — denied
+  console.log(`  scope: ${result.scope}`);
+
+  // --- Batch permission check ---
+  // Evaluates multiple checks in a single round-trip — useful to hydrate
+  // action visibility for many rows without N+1 calls.
+  const checks = [
+    { resourceType: 'STORAGE', action: 'READ', projectId: PROJECT_ID },
+    { resourceType: 'STORAGE', action: 'WRITE', projectId: PROJECT_ID },
+    { resourceType: 'STORAGE', action: 'DELETE', projectId: PROJECT_ID },
+  ];
+  const results = await client.checkPermissionBatch(checks);
+  console.log('\nBatch permission check:');
+  for (let i = 0; i < checks.length; i++) {
+    const { resourceType, action } = checks[i];
+    const { hasPermission, scope } = results[i];
+    console.log(`  ${resourceType}:${action} → hasPermission: ${hasPermission}, scope: ${scope}`);
+  }
+
+  // --- Get project ---
+  const project = await client.getProject(PROJECT_ID!);
+  console.log('\nProject:');
+  console.log(JSON.stringify(project, null, 2));
+
+  // --- Get project data ---
+  // getProjectData returns the full project snapshot: users, roles, files, folders.
+  // User data is stripped of sensitive fields server-side.
+  const data = await client.getProjectData(PROJECT_ID!);
+  console.log('\nProject data (summary):');
+  console.log(`  users: ${data.users?.length ?? 0}`);
+  console.log(`  files: ${data.files?.length ?? 0}`);
+  console.log(`  folders: ${data.folders?.length ?? 0}`);
+}
+
+main().catch(console.error);