@thatopen/services 0.15.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>
@@ -127,6 +129,14 @@ machine lives at:
 https://platform.thatopen.com/dashboard/projects/<PROJECT_ID>/apps/local-app
 ```
 
+> **If the platform shows "failed to load application" and the console says
+> `Permission was denied for this request to access the `loopback` address space`**:
+> current Chrome blocks an https page from fetching `http://localhost` until the
+> user grants the **Local network access** permission. Tell the user: click the
+> icon left of the URL → Site settings → **Local network access** → **Allow**,
+> then reload. One-time, per browser profile. Verified 2026-09-22 — without the
+> grant the dev loop does not work at all; with it, everything below does.
+
 Substitute the project id. That is the local app running inside the platform's own UI, against
 the project's real data. Send the user there rather than to a bare localhost port, which is the
 app without the platform around it.
@@ -257,6 +267,62 @@ engine / UI example sets. Load those indexes before writing code. For an **app**
 must be built with Lit + `@thatopen/ui` (`BUI`)** — consult the design system first. Run the
 scaffold first, then extend it; don't rebuild from scratch.
 
+## 5b. The channel: drive the running app from outside, and multiplayer
+
+The scaffold is already listening. `src/setups/channel.ts` joins the platform
+channel at boot with two typed commands (`ping`, `get-loaded-models`), and a
+collaboration room shared by every open tab of the app. This is the bridge for
+"an LLM on the desktop drives the app" and for multiplayer, and it is the same
+system: the platform relays messages between app tabs and external tools.
+
+To command the app from outside (a script, an MCP server, your own tool):
+
+1. The user creates a **platform token** with the **API** permission
+   (dashboard → Account → Tokens). Same secrecy rules as always.
+2. Connect with `socket.io-client` and subscribe, then publish:
+
+```bash
+npm i socket.io-client   # in the external tool's own project, not the app
+```
+
+```js
+import { io } from "socket.io-client";
+
+const socket = io(`https://platform.thatopen.com?accessToken=${process.env.THATOPEN_TOKEN}`);
+// While iterating with `thatopen serve`, OMIT appId (the dev channel is keyed
+// to the account); pass the appId once the app is published.
+socket.emit("channelSubscribe", { projectId, appId, kind: "cli" });
+socket.on("channelMessage", (msg) => {
+  if (msg.type === "channel:subscribed") {
+    socket.emit(
+      "channelPublish",
+      { type: "ping", requestId: crypto.randomUUID(), payload: { echo: "hi" } },
+      (ack) => console.log(ack), // { delivered: 0 } = no app tab is listening
+    );
+  } else {
+    console.log("app says:", msg);
+  }
+});
+```
+
+A reply to your `requestId` reaches only your socket — a second tool connected
+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
+is the reply. The full walkthrough (typed contracts, collaboration events,
+presence) is `node_modules/@thatopen/services/src/core/examples/channel.ts`,
+indexed in the client API index you already loaded.
+
 ## 6. Publish (when ready)
 
 ```bash
@@ -283,8 +349,10 @@ component, once added to a project, is then triggered by an app or an automation
   four-point plan and waiting for approval to do what was just requested costs the user a whole turn
   and buys nothing. Stop and ask only when you are about to change files you did not create, when
   the request can be read two ways that mean different work, or when the next step is destructive.
-- **Never save to the platform on every change.** Drafts belong in `localStorage` /
-  IndexedDB; the platform gets an explicit save. Writes are capped at 30 per minute and a
+- **Never save to the platform on every change.** Drafts live in memory — the
+  production sandbox runs apps on an opaque origin where `localStorage`,
+  `sessionStorage`, IndexedDB and cookies all **throw** (they work in dev mode
+  and then break for every real user). The platform gets an explicit save. Writes are capped at 30 per minute and a
   `429` loses the write. See
   `node_modules/@thatopen/services/docs/rate-limits.md` before you write any save, sync or
   polling code.

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/docs/rate-limits.md

@@ -74,27 +74,36 @@ try {
 copy of the change was in that request, it is gone — which is the real reason
 the local-draft pattern below matters.
 
-## The pattern: local drafts, explicit saves
+## The pattern: drafts in memory, explicit saves
 
-Keep every intermediate state in the browser. Write to the platform only when
-the user asks for it.
+Keep every intermediate state in memory. Write to the platform only when the
+user asks for it, or on a slow timer.
+
+> **Why not `localStorage`?** Platform apps run in a sandboxed iframe on an
+> **opaque origin**, where `localStorage`, `sessionStorage`, IndexedDB and
+> cookies don't return empty — they **throw, on the property access itself**.
+> Dev mode grants `allow-same-origin`, so origin storage works on the machine
+> of whoever writes the app and fails for every user. This has shipped broken
+> at least once. Inside a platform app there are exactly two stores: memory,
+> and the platform through the client API.
 
 ```ts
-const draftKey = `draft:${fileId}`;
+const drafts = new Map<string, { state: unknown; at: number }>();
 
-function onChange(state: unknown) {
-  localStorage.setItem(draftKey, JSON.stringify({ state, at: Date.now() }));
+function onChange(fileId: string, state: unknown) {
+  drafts.set(fileId, { state, at: Date.now() });
 }
 
-async function onSave(state: unknown) {
+async function onSave(fileId: string, state: unknown) {
   const blob = new Blob([JSON.stringify(state)], { type: 'application/json' });
   await client.updateFile(fileId, { file: blob, versionTag: `v${Date.now()}` });
-  localStorage.removeItem(draftKey);
+  drafts.delete(fileId);
 }
 ```
 
-On load, if a draft exists for the file, offer to restore it. That gives crash
-recovery — the thing autosave was really for — at zero requests.
+A draft in memory does not survive a reload. If surviving one matters, the
+draft itself has to go to the platform — on the explicit save, or on the slow
+timer below — because there is nowhere else to put it.
 
 Rules of thumb:
 
@@ -104,10 +113,11 @@ Rules of thumb:
 - **Never save while a save is in flight.** Keep a flag per file, and drop or
   queue the second save. Overlapping writes also create versions that are hard
   to reconcile.
-- **Big or binary work-in-progress** belongs in IndexedDB, not `localStorage`
-  (about 5 MB per origin).
-- There is **no draft-write method in the client on purpose.** Local storage is
-  the draft store; the platform stores versions the user chose to keep.
+- **Big or binary work-in-progress** stays in memory too — there is no
+  IndexedDB fallback in the sandbox, so size is bounded by RAM, which is fine:
+  it is the same object the app is already editing.
+- There is **no draft-write method in the client on purpose.** Memory is the
+  draft store; the platform stores versions the user chose to keep.
 
 ## Retries
 

package/package.json

@@ -15,7 +15,7 @@
     "access": "public"
   },
   "private": false,
-  "version": "0.15.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/resources/AGENTS.md

@@ -36,12 +36,19 @@ Once you have these, you know everything available on the platform. Only then fe
   **Run it first** (`npm run dev`) to see it work, *then* extend it — don't rebuild a viewer from scratch.
 - **Do the thing they asked for.** If the request already says what to build, build it. Stop and ask only when you are about to change files you did not create, when the request can be read two ways that mean different work, or when the next step is destructive.
 - If something already exists in the indexes, use it — don't reimplement it.
+- **The scaffold already listens on the platform channel** (`src/setups/channel.ts`):
+  external tools (an MCP server, a CLI) command the app through `AppCommands`, and
+  tabs collaborate through `AppCollabEvents`. Extend those maps instead of opening
+  sockets — apps cannot hold their own connection. Walkthrough:
+  `node_modules/@thatopen/services/src/core/examples/channel.ts`.
 
 ## Hard rules (always apply)
 
 1. **Never write to the platform on every change.** No autosave per keystroke,
-   per drag, or inside a render loop. Keep work in progress in `localStorage` /
-   IndexedDB and call the platform on an **explicit user save** (or a timer no
+   per drag, or inside a render loop. Keep work in progress **in memory** — the
+   production sandbox has NO origin storage (`localStorage`, `sessionStorage`,
+   IndexedDB and cookies **throw** on its opaque origin; dev mode hides this) —
+   and call the platform on an **explicit user save** (or a timer no
    faster than once every 30 seconds). Writes are capped at **30 per minute**;
    crossing that returns `429` and the write is **lost**, not queued.
    If the user asks for autosave, build it against local storage and say so.

package/src/cli/templates/app/README.md

@@ -209,6 +209,39 @@ client.onExecutionProgress(executionId, (data) => {
 client.localServerUrl = "http://localhost:4001";
 ```
 
+## The channel: external control + multiplayer
+
+This app ships listening on the platform channel (`src/setups/channel.ts`). Two
+things work out of the box:
+
+- **External tools can command it.** An MCP server, a CLI or a plugin
+  authenticated with a platform token of the same account can send the commands
+  declared in `AppCommands` (`ping`, `get-loaded-models`) and gets typed
+  replies back. This is how a desktop LLM drives the running app.
+- **Tabs of this app see each other.** Every open tab joins a collaboration
+  room shared across accounts (`AppCollabEvents`) — the base for cursors,
+  presence and live sync.
+
+To add a command, extend the map and handle it; whatever you return is the reply:
+
+```ts
+export type AppCommands = {
+  // ...existing commands...
+  "select-by-category": { payload: { category: string }; reply: { count: number } };
+};
+
+external.on("select-by-category", async ({ category }) => {
+  const count = await selectByCategory(category);
+  return { count };
+});
+```
+
+The app never opens a socket: the platform shell owns the connection and relays
+it, which is also the security boundary. Joining is opt-in per room — the
+scaffold joins at boot; move the `join()` calls behind a button to make it a
+user choice. Full walkthrough with a collab example:
+`node_modules/@thatopen/services/src/core/examples/channel.ts`.
+
 ## Configuration
 
 - `.thatopen` — local config (gitignored). Created by `npm run login`; also holds

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

@@ -8,6 +8,7 @@ import * as BUI from "@thatopen/ui";
 import * as MARKERJS from "@markerjs/markerjs3";
 import { PlatformClient, UIManager } from "@thatopen/services";
 import { setAppContext } from "./app";
+import { setupChannel } from "./setups/channel";
 
 // ─── A2 migration — PHASES 1+2: boot on UIManager + re-dock panels ───────────
 // Juan consolidated the old AppManager (layout) + ViewportsManager (viewport)
@@ -39,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
@@ -96,7 +111,19 @@ 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 */
   }

package/src/cli/templates/app/src/setups/channel.ts

@@ -0,0 +1,76 @@
+/**
+ * The platform channel, pre-wired: typed commands that an external tool (an
+ * MCP server, a CLI, a desktop LLM, a plugin) can send this app while it runs,
+ * and a collaboration room where every open tab of this app hears the others.
+ *
+ * The app never opens a socket. The platform shell owns the one connection and
+ * relays over `postMessage`; `client.channel` is the typed layer on top. That
+ * also means this only works inside the platform iframe — `setupChannel` is
+ * called from a try/catch in `main.ts` so the app still boots anywhere else.
+ *
+ * To extend: add a command to {@link AppCommands} and handle it below. What a
+ * handler returns is sent back to whoever asked; throw and they get the error.
+ * Full walkthrough: `node_modules/@thatopen/services/src/core/examples/channel.ts`.
+ */
+import * as OBC from "@thatopen/components";
+import { PlatformClient } from "@thatopen/services";
+
+/**
+ * The contract with external tools. Each command names its payload and, when
+ * the caller waits for an answer, its reply. A command without `reply` is a
+ * notification. This type is the whole API an MCP server sees: keep it honest.
+ */
+export type AppCommands = {
+  /** Liveness check — answer whoever is probing that this app is listening. */
+  ping: { payload: { echo?: string } | undefined; reply: { pong: true; echo?: string } };
+  /** The ids of the models currently loaded in the viewer. */
+  "get-loaded-models": { payload: undefined; reply: { models: string[] } };
+};
+
+/** Events tabs of this app send each other. Events, so no replies. */
+export type AppCollabEvents = {
+  /** Sent once on join, so other tabs can log or greet. Replace with your own. */
+  hello: { at: number };
+};
+
+/**
+ * Wires both rooms and joins them at boot. Joining is what makes the app
+ * reachable — until then, nothing arrives. If you'd rather listen only when
+ * the user opts in, move the `join()` calls behind a button.
+ */
+export function setupChannel(
+  client: PlatformClient,
+  components: OBC.Components,
+) {
+  // Commands from every kind of external tool of this account. Narrow with
+  // `client.channel.external<AppCommands>("mcp")` to hear one kind only.
+  const external = client.channel.external<AppCommands>();
+
+  external.on("ping", (payload) => ({ pong: true as const, echo: payload?.echo }));
+
+  external.on("get-loaded-models", () => {
+    const fragments = components.get(OBC.FragmentsManager);
+    return { models: [...fragments.list.keys()] };
+  });
+
+  // Collaboration: other users' tabs of this same app, across accounts.
+  const collab = client.channel.collab<AppCollabEvents>();
+  collab.on("hello", (event, { from }) => {
+    console.log(`[channel] tab ${from} joined the collaboration`, event);
+  });
+  collab.onPeerLeft(({ from }) => {
+    console.log(`[channel] tab ${from} left the collaboration`);
+  });
+
+  // Fire-and-forget joins: the app is usable with or without the channel, so
+  // a failure is a warning, never a boot error.
+  external
+    .join()
+    .catch((error) => console.warn("[channel] external join failed:", error));
+  collab
+    .join()
+    .then(() => collab.send("hello", { at: Date.now() }))
+    .catch((error) => console.warn("[channel] collab join failed:", error));
+
+  return { external, collab };
+}

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);