@thatopen/services 0.16.0 → 0.17.0

package/src/built-in/UIManager/src/viewer-toolbar/example.ts

@@ -149,28 +149,33 @@ document.body.style.margin = "0";
   gotcha below), then appended as the toolbar's light-DOM content:
 
   ```ts
+  import { html, render } from "lit";
+
   const headlessBar = document.createElement("top-viewer-toolbar");
   headlessBar.toggleAttribute("headless", true);
 
-  const customButtons = document.createElement("bim-toolbar") as unknown as HTMLElement;
-  customButtons.setAttribute("style", "pointer-events: auto;");
+  // A plain container — the `<bim-toolbar>` itself is rendered inside it.
+  const toolbarHost = document.createElement("div");
+  toolbarHost.style.pointerEvents = "auto";
   render(
     html`
-      <bim-toolbar-section label-hidden style="background: transparent;">
-        <top-viewer-mode-toggle-button></top-viewer-mode-toggle-button>
-        <top-viewer-hide-button></top-viewer-hide-button>
-        <top-viewer-select-button></top-viewer-select-button>
-      </bim-toolbar-section>
-      <bim-toolbar-section label-hidden style="background: transparent;">
-        <bim-button
-          icon="mdi:fit-to-page-outline"
-          @click=${() => myOwnFitToViewLogic()}
-        ><bim-tooltip placement="top">Zoom to fit</bim-tooltip></bim-button>
-      </bim-toolbar-section>
+      <bim-toolbar>
+        <bim-toolbar-section label-hidden style="background: transparent;">
+          <top-viewer-mode-toggle-button></top-viewer-mode-toggle-button>
+          <top-viewer-hide-button></top-viewer-hide-button>
+          <top-viewer-select-button></top-viewer-select-button>
+        </bim-toolbar-section>
+        <bim-toolbar-section label-hidden style="background: transparent;">
+          <bim-button
+            icon="mdi:fit-to-page-outline"
+            @click=${() => myOwnFitToViewLogic()}
+          ><bim-tooltip placement="top">Zoom to fit</bim-tooltip></bim-button>
+        </bim-toolbar-section>
+      </bim-toolbar>
     `,
-    customButtons,
+    toolbarHost,
   );
-  headlessBar.appendChild(customButtons);
+  headlessBar.appendChild(toolbarHost);
   // headlessBar can now be appended anywhere inside <top-viewer>.
   ```
 
@@ -208,7 +213,7 @@ document.body.style.margin = "0";
     Custom Elements v1 forbids for elements created imperatively —
     `document.createElement("bim-button")` throws `NotSupportedError`.
     Render them with lit's `render(html\`...\`, container)` instead, exactly
-    like the `customButtons` bar above — never build them by hand.
+    like the `toolbarHost` container above — never build them by hand.
   - **`bim-button` sizes itself** — square when it's icon-only, a consistent
     height when it has a label. Don't set `width`/`height`/`min-width`
     inline on it; that only fights its own layout and produces buttons that
@@ -225,7 +230,13 @@ document.body.style.margin = "0";
   ### 🧩 Standalone buttons reference
 
   Every button the default bar uses is independently importable/usable as
-  its own custom element:
+  its own custom element. They render icon-only with a tooltip; set the
+  optional `label` attribute on any of them to show text next to the icon
+  (the tooltip stays as it is):
+
+  ```html
+  <top-viewer-hide-button label="Hide"></top-viewer-hide-button>
+  ```
 
   | Element | Does |
   |---|---|
@@ -237,16 +248,105 @@ document.body.style.margin = "0";
   | `<top-viewer-focus-button>` | Frames the camera on the target set |
   | `<top-viewer-reset-button>` | Restores full visibility + opacity (global) |
   | `<top-viewer-select-button>` | Activates the default Select tool |
-  | `<top-viewer-clip-button>` | Activates the Clip tool |
+  | `<top-viewer-clip-button>` | Clipping planes: face-placing mode by default, or axis planes / a mode menu via `modes` (see below) |
   | `<top-viewer-measure-length-button>` | Activates length measurement |
   | `<top-viewer-measure-area-button>` | Activates area measurement |
   | `<top-viewer-measure-angle-button>` | Activates angle measurement |
   | `<top-viewer-measure-edge-button>` | Activates edge measurement |
   | `<top-viewer-measure-face-button>` | Activates face measurement |
   | `<top-viewer-measure-volume-button>` | Activates volume measurement |
+  | `<top-viewer-measure-button>` | All measurement modes in one button (a menu by default), or a chosen subset via `modes` (see below) |
   | `<top-viewer-projection-toggle-button>` | Toggles Perspective ⇄ Orthographic |
   | `<top-viewer-walkthrough-button>` | Toggles first-person walkthrough |
+  | `<top-viewer-navigation-button>` | Switches between orbit and first-person navigation (a menu by default), or a single chosen mode via `modes` (see below) |
 
   Each one self-wires from context — drop it anywhere under `<top-viewer>`
   and it works, with no props to pass in.
+
+  ### ✂️ Clip button modes
+
+  Without any attribute, `<top-viewer-clip-button>` enters face-placing mode:
+  double-click a face in the model and a clip plane is dropped on it. The
+  optional `modes` attribute changes what the button offers — a whitespace-
+  (or comma-) separated list of `x`, `y`, `z` and `face` (case-insensitive;
+  unknown tokens are ignored, duplicates dropped, the order you write is the
+  order shown):
+
+  ```html
+  <!-- a menu with four entries: X axis, Y axis, Z axis, Face -->
+  <top-viewer-clip-button modes="x y z face"></top-viewer-clip-button>
+
+  <!-- one mode = no menu; a click creates a horizontal cut right away -->
+  <top-viewer-clip-button modes="y"></top-viewer-clip-button>
+
+  <!-- default: face-placing mode -->
+  <top-viewer-clip-button></top-viewer-clip-button>
+  ```
+
+  - **One mode** — the button runs it directly on click. `face` is the
+    default face-placing behavior.
+  - **Two or more** — clicking opens a menu with one entry per mode ("X
+    axis", "Y axis", "Z axis", "Face"); picking one runs it and closes the
+    menu.
+  - **Axis modes** create a single plane through the center of the bounding
+    box of all loaded models (nothing happens if no model is loaded). Axes
+    follow the three.js convention — **Y is vertical**, so `y` is a
+    horizontal cut. The plane's normal is the *negative* axis — `(-1, 0, 0)`,
+    `(0, -1, 0)`, `(0, 0, -1)` — so the plane clips what lies on the
+    positive side of the axis (`y` removes everything above the middle of
+    the model). Axis planes behave exactly like face-placed ones: same
+    section styling, listed in the objects outliner, draggable by their
+    gizmo, removable with Delete.
+  - The button shows as active only while face-placing mode is on.
+
+  ### 📏 Measure button modes
+
+  `<top-viewer-measure-button>` puts the measurement tools behind a single
+  button. Without any attribute it offers all six modes — `length`, `area`,
+  `angle`, `edge`, `face`, `volume` — in a menu. The optional `modes`
+  attribute picks a subset (whitespace- or comma-separated, case-insensitive;
+  unknown tokens are ignored, duplicates dropped, your order is kept):
+
+  ```html
+  <!-- default: a menu with all six modes -->
+  <top-viewer-measure-button></top-viewer-measure-button>
+
+  <!-- a menu with just these three, in this order -->
+  <top-viewer-measure-button modes="length area volume"></top-viewer-measure-button>
+
+  <!-- one mode = no menu; a click starts that measurement right away -->
+  <top-viewer-measure-button modes="length"></top-viewer-measure-button>
+  ```
+
+  - **One mode** — a click activates it directly, exactly like the matching
+    standalone button (`length` and `area` measure freely; `edge` and `face`
+    snap to edges and faces).
+  - **Two or more** — a click opens a menu with one text-labelled entry per
+    mode ("Length", "Area", "Angle", "Edge", "Face", "Volume"); picking one
+    activates it and closes the menu.
+  - The button shows as active while any of its modes is the active
+    measurement mode, and its icon switches to that mode's icon (a ruler
+    otherwise). In the menu, the active mode's entry is marked.
+
+  ### 🧭 Navigation button modes
+
+  `<top-viewer-navigation-button>` switches how the camera moves. Without any
+  attribute it offers both modes — `orbit` and `first-person` — in a menu.
+  The optional `modes` attribute narrows or reorders them (whitespace- or
+  comma-separated, case-insensitive; unknown tokens are ignored, duplicates
+  dropped, your order is kept):
+
+  ```html
+  <!-- default: a menu with "Orbit" and "First person" -->
+  <top-viewer-navigation-button></top-viewer-navigation-button>
+
+  <!-- one mode = no menu; a click switches straight to it -->
+  <top-viewer-navigation-button modes="orbit"></top-viewer-navigation-button>
+  ```
+
+  - `orbit` turns first-person navigation off (nothing happens if it already
+    is); `first-person` turns it on (nothing happens if it already is) — the
+    same first-person navigation `<top-viewer-walkthrough-button>` toggles.
+  - The button's icon always shows the current mode, and the button is active
+    while first-person is on. In the menu, the current mode's entry is marked.
 */

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