@thatopen/services 0.3.15 → 0.4.0

package/README.md

@@ -1,62 +1,62 @@
-# @thatopen/services
-
-Client library and CLI for building BIM apps and cloud components on [That Open Platform](https://platform.thatopen.com). Apps run inside the platform's browser environment; cloud components run server-side and can be triggered from any app.
-
-> **Using an AI assistant?** Point it at this single file and it can take you from nothing to a running app:
-> → [`docs/ai-quickstart.md`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/ai-quickstart.md)
-
-## Quick Start
-
-### 1. Install the CLI
-
-```bash
-npm install -g @thatopen/services@latest
-```
-
-### 2. Choose a project type
-
-| Type | Template | Use when |
-|------|----------|----------|
-| **App** | `app` | You're building a BIM app that runs in the platform's browser UI |
-| **Cloud component** | `cloud-component` | You're building server-side logic triggered by an app |
-
-### 3. Scaffold
-
-See the full command reference here:
-→ [`docs/cli/create.md`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/cli/create.md)
-
-To use beta engine libraries instead of the stable ones, see:
-→ [`docs/cli/swap.md`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/cli/swap.md)
-
-### 4. Next steps
-
-Once scaffolded, open `AGENTS.md` in the scaffolded project root — it has everything needed to start building.
-
-## Beta engine libraries (Founding Members)
-
-Founding Members get early access to the private beta engine libraries (`@thatopen-platform/*-beta`). The CLI configures access automatically — no npm account or manual token needed.
-
-```bash
-thatopen login --token <your-token>   # API token from the dashboard → Data → API Tokens
-thatopen create my-app --beta         # new project on the beta libraries
-# or, in an existing project:
-thatopen swap --beta                  # toggle the current project to beta
-```
-
-On `--beta`, the CLI fetches your read-only beta npm credentials and writes them to the project's `.npmrc`, so `npm install` resolves the private packages. The `.npmrc` is gitignored — it carries a credential, so don't commit or share it. Access is tied to your membership; non-Founding accounts get a clear message and the project is still created.
-
-## What's in this repository
-
-- **Library** — `EngineServicesClient` and `PlatformClient` for interacting with the That Open API (files, folders, apps, cloud components, executions, permissions).
-- **CLI** — `thatopen` command for scaffolding and publishing.
-- **Built-in component types** — TypeScript stubs for platform-hosted components.
-
-## Docs
-
-Full reference for all CLI commands and flags:
-→ [`docs/cli/paths.json`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/cli/paths.json)
-
-## Contributing
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, build commands, and publishing workflow.
-
+# @thatopen/services
+
+Client library and CLI for building BIM apps and cloud components on [That Open Platform](https://platform.thatopen.com). Apps run inside the platform's browser environment; cloud components run server-side and can be triggered from any app.
+
+> **Using an AI assistant?** Point it at this single file and it can take you from nothing to a running app:
+> → [`docs/ai-quickstart.md`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/ai-quickstart.md)
+
+## Quick Start
+
+### 1. Install the CLI
+
+```bash
+npm install -g @thatopen/services@latest
+```
+
+### 2. Choose a project type
+
+| Type | Template | Use when |
+|------|----------|----------|
+| **App** | `app` | You're building a BIM app that runs in the platform's browser UI |
+| **Cloud component** | `cloud-component` | You're building server-side logic triggered by an app |
+
+### 3. Scaffold
+
+See the full command reference here:
+→ [`docs/cli/create.md`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/cli/create.md)
+
+To use beta engine libraries instead of the stable ones, see:
+→ [`docs/cli/swap.md`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/cli/swap.md)
+
+### 4. Next steps
+
+Once scaffolded, open `AGENTS.md` in the scaffolded project root — it has everything needed to start building.
+
+## Beta engine libraries (Founding Members)
+
+Founding Members get early access to the private beta engine libraries (`@thatopen-platform/*-beta`). The CLI configures access automatically — no npm account or manual token needed.
+
+```bash
+thatopen login --token <your-token>   # API token from the dashboard → Data → API Tokens
+thatopen create my-app --beta         # new project on the beta libraries
+# or, in an existing project:
+thatopen swap --beta                  # toggle the current project to beta
+```
+
+On `--beta`, the CLI fetches your read-only beta npm credentials and writes them to the project's `.npmrc`, so `npm install` resolves the private packages. The `.npmrc` is gitignored — it carries a credential, so don't commit or share it. Access is tied to your membership; non-Founding accounts get a clear message and the project is still created.
+
+## What's in this repository
+
+- **Library** — `EngineServicesClient` and `PlatformClient` for interacting with the That Open API (files, folders, apps, cloud components, executions, permissions).
+- **CLI** — `thatopen` command for scaffolding and publishing.
+- **Built-in component types** — TypeScript stubs for platform-hosted components.
+
+## Docs
+
+Full reference for all CLI commands and flags:
+→ [`docs/cli/paths.json`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/cli/paths.json)
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, build commands, and publishing workflow.
+

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

@@ -370,6 +370,11 @@ declare class _CDEManager extends OBC.Component implements OBC.Transitionable<CD
         success: boolean;
         error?: string;
     }>;
+    /** Fires when `_derivedFileIds` finishes a (re)sync — consumers that filter
+     *  or resolve by source↔derived link (e.g. `top-files-panel` hiding an
+     *  already-linked `.frag` row) should reload on this, since it can complete
+     *  after `onFilesChanged` already fired with the (still unsynced) list. */
+    readonly onDerivedFileIdsChanged: OBC.Event<Record<string, string>>;
     readonly conversionProgress: Map<string, number>;
     enabled: boolean;
     projectName: string;
@@ -390,6 +395,14 @@ declare class _CDEManager extends OBC.Component implements OBC.Transitionable<CD
     }[];
     get viewableExtensions(): Set<string>;
     private _files;
+    /** ifcFileId → its linked derivedFileId (FRAG today; other source formats
+     *  once they get a converter too), read from each IFC's own version
+     *  metadata. Kept as an in-memory cache — synced by `_syncDerivedFileIds`
+     *  whenever `_files` is (re)set, or right after a conversion succeeds —
+     *  rather than fetched live per call, so `resolveViewFile` can stay a plain
+     *  synchronous lookup (same contract as before, no ripple into
+     *  `sendMachineEvent`'s callers). */
+    private _derivedFileIds;
     private _folders;
     private _fileHistory;
     private _metadataSchema;
@@ -423,6 +436,8 @@ declare class _CDEManager extends OBC.Component implements OBC.Transitionable<CD
     get machineState(): CDEMachineState;
     get files(): CDEFile[];
     set files(value: CDEFile[]);
+    /** ifcFileId → derivedFileId — see `_derivedFileIds`. */
+    get derivedFileIds(): Record<string, string>;
     get folders(): ItemFolder[];
     set folders(value: ItemFolder[]);
     get showArchived(): boolean;
@@ -463,10 +478,12 @@ declare class _CDEManager extends OBC.Component implements OBC.Transitionable<CD
     loadUserConfig(): Promise<{
         visibleColumns?: string[];
         metadataViews?: CDEMetadataView[];
+        hideDerivedFiles?: boolean;
     } | null>;
     saveUserConfig(config: {
         visibleColumns?: string[];
         metadataViews?: CDEMetadataView[];
+        hideDerivedFiles?: boolean;
     }): Promise<string | undefined>;
     loadMetadataSchema(): Promise<void>;
     initMetadataViews(views: CDEMetadataView[], activeId: string | null): void;
@@ -481,7 +498,23 @@ declare class _CDEManager extends OBC.Component implements OBC.Transitionable<CD
         file: CDEFile;
         existing: CDEFile;
     }[];
+    /** Which file to actually load when the user views `file` — its linked FRAG
+     *  if it has one, else the IFC itself. Reads `_derivedFileIds` (the IFC's
+     *  own version metadata, kept in sync — see `_syncDerivedFileIds`), NOT a
+     *  name+folder match anymore. Stays synchronous: `_derivedFileIds` is a
+     *  pre-synced in-memory cache, so this is a plain lookup, keeping the
+     *  contract every existing caller (`sendMachineEvent`'s `VIEW` case,
+     *  `top-files-panel`'s "add to view" actions) already relies on. */
     resolveViewFile(file: CDEFile): CDEFile;
+    /** Populates `_derivedFileIds` from every IFC's own version metadata — the
+     *  source of truth for the IFC↔FRAG link (same mechanism as `models-list`'s
+     *  `_syncDerivedFileIds`). Reads the unified `derivedFileId` key, falling
+     *  back to the legacy `fragmentsFileId` key that `IfcFragmenter` still
+     *  stamps until it's updated (see issue #3, Task 3). Called whenever
+     *  `_files` is (re)set and right after a conversion succeeds — never
+     *  cached indefinitely, so a reconversion or manual metadata edit is picked
+     *  up on the next sync instead of going stale. */
+    private _syncDerivedFileIds;
     private _saveConversionIndex;
     private _loadConversionIndex;
     private _resumePendingConversions;
@@ -610,6 +643,59 @@ export interface MarkerGroup {
     count: number;
     status?: ClashStatus;
 }
+/** `clashes.frag`'s path relative to `__project_data/`, for consumers that
+ *  persist it via `projectStorageContext` instead of talking to `client`
+ *  directly (see `buildClashBuffer`). */
+export declare const CLASH_DATA_PATH = "collider/clashes.frag";
+export interface ExecutionEntry {
+    jobId: string;
+    executionId: string;
+    startedAt: string;
+}
+/** `cachedFileId`, when given, skips folder/file resolution (3 of the 4
+ *  network round-trips this normally takes) — the file's ID never changes
+ *  once created, so callers that already know it (see `ClashesManager`'s
+ *  `_clashFragFileId`) should always pass it. */
+export declare function ensureClashFragFileId(client: PlatformClient, projectId: string, cachedFileId?: string): Promise<string>;
+export declare function getExecutions(client: PlatformClient, projectId: string | undefined): Promise<ExecutionEntry[]>;
+export interface ClashData {
+    jobs: ClashJob[];
+    runs: ClashRun[];
+    clashes: Clash[];
+    queries: ClashQuery[];
+    matrices: ClashMatrix[];
+    /** Resolved once here — callers should cache and pass back into
+     *  `loadClashData`/`buildClashBuffer` as `cachedFileId` to skip
+     *  re-resolving it (see `ensureClashFragFileId`). */
+    fileId: string;
+}
+export declare function loadClashData(client: PlatformClient, projectId: string, cachedFileId?: string): Promise<ClashData>;
+/**
+ * Diffs `data` against the persisted `clashes.frag` and builds the updated
+ * buffer, WITHOUT uploading it — callers decide how/where to persist the
+ * result (direct `client.updateFile`, via `projectStorageContext`, etc).
+ * Still reads the current file via `client` to diff against (job/id
+ * reconciliation needs the previous state), same as `saveClashData` always did.
+ */
+export declare function buildClashBuffer(client: PlatformClient, projectId: string, data: {
+    queries: ClashQuery[];
+    matrices: ClashMatrix[];
+    jobs: ClashJob[];
+    clashes: Clash[];
+}, onJobsReconciled: (toAdd: ClashJob[], toRemove: Set<string>) => void, cachedFileId?: string): Promise<{
+    blob: Blob;
+    fileId: string;
+}>;
+/** Default persistence path: builds the buffer and uploads it straight to
+ *  `client`. Kept as the manager's out-of-the-box behavior for any consumer
+ *  that never overrides `ClashesManager.save` (e.g. doesn't route through
+ *  `projectStorageContext`). */
+export declare function saveClashData(client: PlatformClient, projectId: string, data: {
+    queries: ClashQuery[];
+    matrices: ClashMatrix[];
+    jobs: ClashJob[];
+    clashes: Clash[];
+}, onJobsReconciled: (toAdd: ClashJob[], toRemove: Set<string>) => void): Promise<void>;
 declare class _ClashesManager extends OBC.Component {
     static readonly uuid: "2c9f4e8d-3a1b-4c5e-9d7f-0a2b6c8e1d3f";
     enabled: boolean;
@@ -655,6 +741,10 @@ declare class _ClashesManager extends OBC.Component {
     get ready(): boolean;
     private _client?;
     private _projectId?;
+    /** `clashes.frag`'s file ID, resolved once by `init()`/`reload()`'s
+     *  `loadClashData` call. Never changes once the file exists — passing it
+     *  into `buildClashBuffer` skips 3 of its 4 network round-trips. */
+    private _clashFragFileId?;
     private _reconnectingJobIds;
     private _queries;
     private _matrices;
@@ -670,9 +760,25 @@ declare class _ClashesManager extends OBC.Component {
     get matrices(): ClashMatrix[];
     set matrices(value: ClashMatrix[]);
     private _scheduleSave;
+    /** Chains onto any save already in flight instead of firing a second,
+     *  concurrent `_doSave()` — two overlapping calls would race on
+     *  `buildClashBuffer`'s read-diff-reconcile cycle (real network I/O;
+     *  `onJobsReconciled` mutating `this.jobs` from two stale reads at once)
+     *  and on the upload itself. It also keeps `flush()` correct: it just
+     *  awaits `_savePromise`, so if that got overwritten by a newer, unrelated
+     *  save instead of chained, flush() could resolve while an earlier save
+     *  was still genuinely in flight. */
+    private _queueSave;
     private _doSave;
     /** Cancela el debounce pendiente y ejecuta el save inmediatamente. Espera a que complete. */
     flush(): Promise<void>;
+    /**
+     * Builds the current `clashes.frag` buffer (diffed/reconciled against what's
+     * persisted) WITHOUT uploading it. For consumers (e.g. `clashes-panel`) that
+     * override `save` to persist via `projectStorageContext` instead of the
+     * default direct-`client` path.
+     */
+    buildClashBuffer(): Promise<Blob>;
     get jobs(): ClashJob[];
     set jobs(value: ClashJob[]);
     get runs(): ClashRun[];
@@ -681,8 +787,12 @@ declare class _ClashesManager extends OBC.Component {
     set clashes(value: Clash[]);
     queryById(id: string): ClashQuery | undefined;
     private _clashStylesRegistered;
-    private readonly STYLE_A;
-    private readonly STYLE_B;
+    /** Green — elementA's highlight color. Public so consumers (e.g. "create
+     *  topic from clash") can build a matching BCF viewpoint `componentColors`
+     *  entry without duplicating the hex value. */
+    readonly STYLE_A = "#22c55e";
+    /** Red — elementB's highlight color. Same reasoning as `STYLE_A`. */
+    readonly STYLE_B = "#ef4444";
     private _clashStyle;
     highlightAllClashes(clashes: Clash[]): void;
     ghostClashes(clashes: Clash[]): Promise<void>;
@@ -863,6 +973,59 @@ export type HelloWorld = InstanceType<typeof _HelloWorld>;
 export declare const HelloWorld: typeof _HelloWorld & {
     uuid: "2c4ae432-fc24-43e9-9783-0c960c674e96";
 };
+/** `main.bcf`'s path relative to `__project_data/` — shared with
+ *  `requestBcfSave` (`UIManager/src/utils/bcf-storage.ts`) so both sides of
+ *  the save/load round-trip agree on where the file lives. */
+export declare const BCF_DATA_PATH = "topics/main.bcf";
+/** Downloads `__project_data/topics/main.bcf` and loads it into `BCFTopics`,
+ *  if it already has content. A freshly-created file is empty (0 bytes) —
+ *  not a valid BCF zip — so there's nothing to load yet in that case. */
+export declare function loadBcfTopics(client: PlatformClient, projectId: string, components: OBC.Components): Promise<void>;
+/**
+ * Wires up everything `top-topics-panel` (and `clashes-panel`'s "create
+ * topic from clash" feature) needs to work out of the box: `BCFTopics`
+ * configuration (version, author, assignable users — all from real project
+ * data), loading whatever BCF was previously saved for this project, and
+ * resolving `Viewpoints.world` — including backfilling it onto viewpoints
+ * restored from a saved BCF before the 3D world existed yet (`top-viewer`
+ * only creates its `World` once `top-app` finishes mounting, which is later
+ * than `init()` typically runs).
+ */
+declare class _TopicsManager extends OBC.Component {
+    static readonly uuid: "69af63aa-19ba-4fc7-b17b-75647bac1d76";
+    enabled: boolean;
+    /**
+     * Consumer apps call this once — same pattern as `ClashesManager.init(client)`
+     * — instead of wiring `BCFTopics.setup()`, loading the saved BCF, and
+     * backfilling viewpoint worlds by hand.
+     */
+    init(client: PlatformClient): Promise<void>;
+    private _firstWorld;
+}
+/**
+ * Wires up everything `top-topics-panel` (and `clashes-panel`'s "create
+ * topic from clash" feature) needs to work out of the box: `BCFTopics`
+ * configuration (version, author, assignable users — all from real project
+ * data), loading whatever BCF was previously saved for this project, and
+ * resolving `Viewpoints.world` — including backfilling it onto viewpoints
+ * restored from a saved BCF before the 3D world existed yet (`top-viewer`
+ * only creates its `World` once `top-app` finishes mounting, which is later
+ * than `init()` typically runs).
+ */
+export type TopicsManager = InstanceType<typeof _TopicsManager>;
+/**
+ * Wires up everything `top-topics-panel` (and `clashes-panel`'s "create
+ * topic from clash" feature) needs to work out of the box: `BCFTopics`
+ * configuration (version, author, assignable users — all from real project
+ * data), loading whatever BCF was previously saved for this project, and
+ * resolving `Viewpoints.world` — including backfilling it onto viewpoints
+ * restored from a saved BCF before the 3D world existed yet (`top-viewer`
+ * only creates its `World` once `top-app` finishes mounting, which is later
+ * than `init()` typically runs).
+ */
+export declare const TopicsManager: typeof _TopicsManager & {
+    uuid: "69af63aa-19ba-4fc7-b17b-75647bac1d76";
+};
 declare class _UIManager extends OBC.Component {
     #private;
     static readonly uuid: "234f1416-528d-452a-9cc9-a16c5239b2eb";

package/dist/cli.js

@@ -4205,8 +4205,8 @@ class BaseXHR extends Polling {
   /**
    * Sends data.
    *
-   * @param {String} data to send.
-   * @param {Function} called upon flush.
+   * @param {String} data - data to send.
+   * @param {Function} fn - called upon flush.
    * @private
    */
   doWrite(data, fn) {
@@ -4959,7 +4959,7 @@ class SocketWithoutUpgrade extends Emitter {
   /**
    * Sends a packet.
    *
-   * @param {String} type: packet type.
+   * @param {String} type - packet type.
    * @param {String} data.
    * @param {Object} options.
    * @param {Function} fn - callback function.
@@ -5194,11 +5194,12 @@ class SocketWithUpgrade extends SocketWithoutUpgrade {
 }
 let Socket$1 = class Socket extends SocketWithUpgrade {
   constructor(uri, opts = {}) {
-    const o = typeof uri === "object" ? uri : opts;
+    const isOptionsOnly = typeof uri === "object";
+    const o = isOptionsOnly ? { ...uri } : { ...opts };
     if (!o.transports || o.transports && typeof o.transports[0] === "string") {
       o.transports = (o.transports || ["polling", "websocket", "webtransport"]).map((transportName) => transports[transportName]).filter((t) => !!t);
     }
-    super(uri, o);
+    super(isOptionsOnly ? o : uri, o);
   }
 };
 function url(uri, path2 = "", loc) {
@@ -5419,12 +5420,13 @@ class Encoder {
 class Decoder extends Emitter {
   /**
    * Decoder constructor
-   *
-   * @param {function} reviver - custom reviver to pass down to JSON.stringify
    */
-  constructor(reviver) {
+  constructor(opts) {
     super();
-    this.reviver = reviver;
+    this.opts = Object.assign({
+      reviver: void 0,
+      maxAttachments: 10
+    }, typeof opts === "function" ? { reviver: opts } : opts);
   }
   /**
    * Decodes an encoded packet string into packet JSON.
@@ -5484,7 +5486,13 @@ class Decoder extends Emitter {
       if (buf != Number(buf) || str.charAt(i) !== "-") {
         throw new Error("Illegal attachments");
       }
-      p.attachments = Number(buf);
+      const n = Number(buf);
+      if (!isInteger(n) || n < 0) {
+        throw new Error("Illegal attachments");
+      } else if (n > this.opts.maxAttachments) {
+        throw new Error("too many attachments");
+      }
+      p.attachments = n;
     }
     if ("/" === str.charAt(i + 1)) {
       const start = i + 1;
@@ -5525,7 +5533,7 @@ class Decoder extends Emitter {
   }
   tryParse(str) {
     try {
-      return JSON.parse(str, this.reviver);
+      return JSON.parse(str, this.opts.reviver);
     } catch (e) {
       return false;
     }
@@ -5587,6 +5595,9 @@ class BinaryReconstructor {
     this.buffers = [];
   }
 }
+const isInteger = Number.isInteger || function(value2) {
+  return typeof value2 === "number" && isFinite(value2) && Math.floor(value2) === value2;
+};
 function isObject(value2) {
   return Object.prototype.toString.call(value2) === "[object Object]";
 }
@@ -6946,7 +6957,7 @@ class EngineServicesClient {
     return this.accessToken;
   }
   async #requestApi(method, path2, requestData) {
-    const { body, query, contentType, retries } = requestData || {};
+    const { body, query, contentType, retries, responseType } = requestData || {};
     const url2 = this.#buildUrl(path2);
     const cleanQuery = this.#cleanData(query);
     const token = await this.resolveAccessToken();
@@ -6975,6 +6986,9 @@ class EngineServicesClient {
           textResponse
         );
       }
+      if (responseType === "blob") {
+        return await response.blob();
+      }
       return response.json().then((data) => data).catch(() => void 0);
     } catch (e) {
       let retriesAmmount = retries != null ? retries : this.retries;
@@ -8213,7 +8227,7 @@ Dual licenced under the MIT license or GPLv3. See https://raw.github.com/Stuk/js
 JSZip uses the library pako released under the MIT license :
 https://github.com/nodeca/pako/blob/main/LICENSE
 */
-(function(module2, exports$1) {
+(function(module2, exports) {
   !function(e) {
     module2.exports = e();
   }(function() {

package/dist/core/client.d.ts

@@ -219,6 +219,7 @@ export declare class EngineServicesClient {
         query?: object;
         contentType?: 'application/json' | 'multipart/form-data' | 'application/x-www-form-urlencoded';
         retries?: number;
+        responseType?: 'json' | 'blob';
     }): Promise<T>;
     /**
      * Lists all files accessible by the current token.

package/dist/core/platform-client.d.ts

@@ -86,6 +86,13 @@ export declare class PlatformClient extends EngineServicesClient {
      * User data is stripped of sensitive fields server-side.
      */
     getProjectData(projectId: string): Promise<ProjectData>;
+    /**
+     * Fetches a user's profile picture as raw image bytes, for showing member
+     * avatars inside an app. The route is bearer-authed, so it can't be used as
+     * an `<img src>` — turn the blob into an object URL with
+     * `URL.createObjectURL(blob)`. Rejects when the account has no avatar.
+     */
+    getAvatar(accountId: string): Promise<Blob>;
     /**
      * Checks whether the caller has a specific permission within a project.
      * Returns `{ hasPermission, scope }` where `scope` is `'global'` for