@thatopen/services 0.13.0 → 0.15.0

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

@@ -1585,19 +1585,21 @@ export interface OriginData {
     height: number;
     rotation: number;
 }
-export interface BimSite {
-    label: string;
-    description?: string;
-    lat: number;
-    lon: number;
-    height: number;
-    rotation: number;
-    /** Column-major 4x4 matrix (16 values) mapping BIM local space to the site's georeferenced frame. */
-    baseMatrix: number[];
-}
-export interface BimCoordinatesData {
-    defaultSiteId?: string;
-    sites: Record<string, BimSite>;
+/** Project-wide coordinate reference system + vertical datum config, shared by
+ *  every asset type that needs to decode raw projected coordinates (point
+ *  clouds, BIM) — see automatic-file-derived-georeferencing.md
+ *  (VisorUnificadoAqualia/docs/adrs). One value per project, not per asset:
+ *  every file at the same real-world site shares the same CRS/geoid. */
+export interface CrsData {
+    /** EPSG code of the project's projected CRS (e.g. 25830 for ETRS89/UTM 30N).
+     *  EPSG is a global registry, not region-specific — every project has an
+     *  applicable code, most commonly a standard UTM zone. */
+    epsgCode: number;
+    /** Geoid undulation in meters at the project's origin (orthometric ->
+     *  ellipsoidal height correction). Sampled once from a geoid model
+     *  (client-supplied, or a global EGM2008 fallback) — varies negligibly
+     *  across a single project's extent, so one scalar per project suffices. */
+    geoidUndulation: number;
 }
 export type AssetCoordinateType = "splat" | "ifc" | "point-cloud" | (string & {});
 export interface AssetCoordinate {
@@ -1653,7 +1655,7 @@ export interface ProjectManagerData {
     namespaces: Record<ProjectNamespaceKey, ProjectNamespace>;
     entities: {
         origin: ProjectEntity<OriginData>;
-        bimCoordinates: ProjectEntity<BimCoordinatesData>;
+        crs: ProjectEntity<CrsData>;
         assetCoordinates: ProjectEntity<AssetCoordinate[]>;
         graphicsSettings: ProjectEntity<GraphicsSettingsData>;
     };
@@ -1663,19 +1665,15 @@ export interface SingletonEntity<T> {
     set(data: T): Promise<void>;
     update(partial: Partial<T>): Promise<void>;
 }
-export interface BimCoordinatesEntity {
-    get(): BimCoordinatesData;
-    getSites(): Record<string, BimSite>;
-    getSite(siteId: string): BimSite | undefined;
-    getDefaultSite(): BimSite | undefined;
-    /** Creates a new site. `ProjectManager` generates the opaque `siteId` — callers
-     *  never invent their own (see the class-level JSDoc on `ProjectManager` for why). */
-    createSite(site: BimSite): Promise<string>;
-    /** Updates a site that already exists (from `createSite`). Throws if `siteId`
-     *  isn't in `sites` — this is not an upsert; use `createSite` to add one. */
-    setSite(siteId: string, site: BimSite): Promise<void>;
-    setDefaultSite(siteId: string): Promise<void>;
-    removeSite(siteId: string): Promise<void>;
+/**
+ * A singleton entity that also announces its own changes — for values other
+ * code needs to react to live (recompute/reposition something) rather than
+ * just read on demand. `onChange` fires with the new value on every
+ * `set`/`update`, regardless of whether that change has been persisted yet
+ * (see `ProjectManager.dirty`/`onDirtyChange`).
+ */
+export interface ReactiveSingletonEntity<T> extends SingletonEntity<T> {
+    onChange: import('@thatopen/components').Event<T>;
 }
 export interface AssetCoordinatesEntity {
     getAll(): AssetCoordinate[];
@@ -1698,18 +1696,10 @@ export interface AssetCoordinatesEntity {
  * Schema shape (see `src/types.ts` for the full rationale):
  * - `namespaces`/`entities` are maps keyed by a fixed, readable slug — a
  *   closed set this code defines, never created at runtime.
- * - `bimCoordinates.data.sites` is the one open, runtime-created collection
- *   today, so its keys are opaque generated ids instead of slugs.
- * - `origin`/`graphicsSettings` are singletons; `sites`/`assetCoordinates`
- *   are collections.
+ * - `origin`/`crs`/`graphicsSettings` are singletons; `assetCoordinates` is
+ *   a collection.
  * - `entities[id]` is a uniform envelope: `namespaceId`, mandatory `label`,
  *   optional `description` (omitted, not stored empty), free-form `data`.
- *
- * Id generation rule: whenever a collection needs an opaque id (today just
- * `sites`, potentially more collections later), `ProjectManager` generates it
- * internally (`crypto.randomUUID()`, no prefix) — callers never invent their
- * own. `createSite` is the current example; follow the same pattern for any
- * future `create*` method.
  */
 declare class _ProjectManager extends OBC.Component {
     static readonly uuid: "6f3a9c2e-8b1d-4e6a-9c3f-1d7b5a8e2c4f";
@@ -1720,6 +1710,31 @@ declare class _ProjectManager extends OBC.Component {
     private _loadingData;
     readonly onSaveStart: OBC.Event<void>;
     readonly onSaveComplete: OBC.Event<boolean>;
+    /**
+     * Entity ids (e.g. `"origin"`) with changes not yet persisted. Most entities
+     * auto-save (see `_scheduleSave`) so they're only ever dirty for the instant
+     * before their debounce fires — `origin` is the exception: its `set`/`update`
+     * mark it dirty WITHOUT scheduling a save (see `origin` below), so a caller
+     * driving it continuously (e.g. a drag gizmo) can update it every frame
+     * without spamming the network, and a UI can surface "unsaved changes" +
+     * call `flush()` once the user explicitly confirms.
+     *
+     * KNOWN GAP: `_doSave()` persists the whole `_data` blob (one JSON file for
+     * every entity), so an auto-saving entity's save will also flush out
+     * whatever `origin` currently holds in memory, even if the user hasn't
+     * confirmed it yet — there's no separate "committed vs. draft" copy of
+     * `origin`'s data. Accepted for now as a v1 gap (same spirit as this
+     * package's other documented v1 gaps, see the ProjectManager ADR); revisit
+     * if that coincidence turns out to matter in practice.
+     */
+    private _dirtyEntities;
+    /** True while any entity has unsaved changes. */
+    get dirty(): boolean;
+    /** Ids of entities with unsaved changes right now. */
+    get dirtyEntities(): string[];
+    /** Fires with the current `dirtyEntities` list every time it changes. */
+    readonly onDirtyChange: OBC.Event<string[]>;
+    private _markDirty;
     private _client?;
     private _fileId?;
     private _data;
@@ -1728,15 +1743,26 @@ declare class _ProjectManager extends OBC.Component {
     private _scheduleSave;
     private _queueSave;
     private _doSave;
-    /** Cancels the pending debounce and runs the save immediately. Awaits completion. */
+    /**
+     * Cancels the pending debounce (if any) and runs the save immediately.
+     * Also the only way to persist an entity that marks itself dirty WITHOUT
+     * auto-scheduling (currently just `origin`) — call this once the user
+     * explicitly confirms. Awaits completion.
+     */
     flush(): Promise<void>;
     init(client: PlatformClient): Promise<void>;
-    /** Opaque id generator for any collection needing one (currently just
-     *  `bimCoordinates.sites`) — see the class-level JSDoc's id-generation rule. */
-    private _generateId;
-    origin: SingletonEntity<OriginData>;
+    /**
+     * NOT auto-saving, unlike every other entity below — `set`/`update` mark it
+     * dirty and fire `onChange` immediately, but leave persisting up to an
+     * explicit `flush()` call. This is what lets a continuous interaction (e.g.
+     * a drag gizmo) update `origin` every frame — live for anyone listening to
+     * `onChange` — without writing to the network on every tick, while still
+     * surfacing "there's an unconfirmed change" via `dirty`/`onDirtyChange` for
+     * a UI to gate behind an explicit save action.
+     */
+    origin: ReactiveSingletonEntity<OriginData>;
+    crs: ReactiveSingletonEntity<CrsData>;
     graphicsSettings: SingletonEntity<GraphicsSettingsData>;
-    bimCoordinates: BimCoordinatesEntity;
     assetCoordinates: AssetCoordinatesEntity;
     getNamespaces(): Record<ProjectNamespaceKey, ProjectNamespace>;
     getNamespace(key: ProjectNamespaceKey): Record<string, unknown>;
@@ -1755,18 +1781,10 @@ declare class _ProjectManager extends OBC.Component {
  * Schema shape (see `src/types.ts` for the full rationale):
  * - `namespaces`/`entities` are maps keyed by a fixed, readable slug — a
  *   closed set this code defines, never created at runtime.
- * - `bimCoordinates.data.sites` is the one open, runtime-created collection
- *   today, so its keys are opaque generated ids instead of slugs.
- * - `origin`/`graphicsSettings` are singletons; `sites`/`assetCoordinates`
- *   are collections.
+ * - `origin`/`crs`/`graphicsSettings` are singletons; `assetCoordinates` is
+ *   a collection.
  * - `entities[id]` is a uniform envelope: `namespaceId`, mandatory `label`,
  *   optional `description` (omitted, not stored empty), free-form `data`.
- *
- * Id generation rule: whenever a collection needs an opaque id (today just
- * `sites`, potentially more collections later), `ProjectManager` generates it
- * internally (`crypto.randomUUID()`, no prefix) — callers never invent their
- * own. `createSite` is the current example; follow the same pattern for any
- * future `create*` method.
  */
 export type ProjectManager = InstanceType<typeof _ProjectManager>;
 /**
@@ -1783,18 +1801,10 @@ export type ProjectManager = InstanceType<typeof _ProjectManager>;
  * Schema shape (see `src/types.ts` for the full rationale):
  * - `namespaces`/`entities` are maps keyed by a fixed, readable slug — a
  *   closed set this code defines, never created at runtime.
- * - `bimCoordinates.data.sites` is the one open, runtime-created collection
- *   today, so its keys are opaque generated ids instead of slugs.
- * - `origin`/`graphicsSettings` are singletons; `sites`/`assetCoordinates`
- *   are collections.
+ * - `origin`/`crs`/`graphicsSettings` are singletons; `assetCoordinates` is
+ *   a collection.
  * - `entities[id]` is a uniform envelope: `namespaceId`, mandatory `label`,
  *   optional `description` (omitted, not stored empty), free-form `data`.
- *
- * Id generation rule: whenever a collection needs an opaque id (today just
- * `sites`, potentially more collections later), `ProjectManager` generates it
- * internally (`crypto.randomUUID()`, no prefix) — callers never invent their
- * own. `createSite` is the current example; follow the same pattern for any
- * future `create*` method.
  */
 export declare const ProjectManager: typeof _ProjectManager & {
     uuid: "6f3a9c2e-8b1d-4e6a-9c3f-1d7b5a8e2c4f";

package/dist/core/channel.d.ts

@@ -0,0 +1,198 @@
+/**
+ * The app side of the platform channel: rooms an app can join, and the
+ * messages it exchanges through them.
+ *
+ * The app never holds a socket. The platform shell, outside the iframe, owns
+ * the connection and relays over `postMessage`; this module is the typed
+ * layer on top of that contract, reached as {@link PlatformClient.channel}.
+ */
+/** What a command looks like: the payload it carries and the reply it expects. */
+export interface ChannelCommandShape {
+    payload?: unknown;
+    reply?: unknown;
+}
+/**
+ * The default command map, when none is given: every command name is allowed
+ * and nothing is typed. Give `external<Commands>()` your own map to get
+ * payloads and replies checked at compile time.
+ */
+export type AnyChannelCommands = Record<string, ChannelCommandShape>;
+/** The default event map for {@link CollabRoom}: any name, any payload. */
+export type AnyChannelEvents = Record<string, unknown>;
+type PayloadOf<T> = 'payload' extends keyof T ? T['payload'] : undefined;
+type ReplyOf<T> = 'reply' extends keyof T ? T['reply'] : void;
+/** Someone else on the other end of a room. `kind` is set for external channels. */
+export interface ChannelPeer {
+    from: string;
+    kind?: string;
+}
+/** Who sent a message, and when. */
+export interface ChannelMessageMeta {
+    /** The sender's connection id, stamped by the platform. */
+    from: string;
+    at: number;
+    /** Present when the sender expects an answer. */
+    requestId?: string;
+    /** For an external sender that declared one: `'mcp'`, `'cli'`, `'revit'`… */
+    kind?: string;
+}
+/** How the client talks to the shell. Replaceable, so it can be tested. */
+export interface ChannelTransport {
+    post(message: Record<string, unknown>): void;
+    listen(handler: (data: unknown) => void): () => void;
+}
+/**
+ * Talks to the platform shell through `window.parent`. Only messages whose
+ * `source` is the parent window are accepted — the same check the shell makes
+ * in the other direction — so another frame on the page cannot inject messages
+ * into the app.
+ */
+export declare function windowTransport(): ChannelTransport;
+/** A message as the platform delivers it to the app. */
+export interface ChannelIncomingMessage {
+    type: string;
+    requestId?: string;
+    payload?: unknown;
+    at: number;
+    from: string;
+    scope?: 'collab' | 'external';
+    kind?: string;
+}
+/** What a room did with a message. */
+export type ChannelOutcome = {
+    handled: false;
+} | {
+    handled: true;
+    value?: unknown;
+    error?: string;
+};
+/** What every room shares: membership, peers and presence. */
+export declare abstract class ChannelRoom {
+    #private;
+    private readonly transport;
+    private readonly controls;
+    constructor(transport: ChannelTransport, controls: {
+        join: Record<string, unknown>;
+        leave: Record<string, unknown>;
+    });
+    /** Whether the platform has confirmed this tab is in the room. */
+    get joined(): boolean;
+    /** Who else is in the room right now, as the platform last reported. */
+    get peers(): readonly ChannelPeer[];
+    /**
+     * Enters the room. Resolves when the platform confirms; rejects if it
+     * refuses or does not answer in time. Joining twice is harmless.
+     */
+    join(): Promise<void>;
+    /** Leaves the room. Handlers stay registered, so `join()` resumes them. */
+    leave(): Promise<void>;
+    /** Fires when `joined` or `peers` changes. Returns a function that stops it. */
+    onChange(listener: () => void): () => void;
+    onPeerJoined(listener: (peer: ChannelPeer) => void): () => void;
+    onPeerLeft(listener: (peer: ChannelPeer) => void): () => void;
+    /** @internal Does a message arriving with this scope/kind belong to this room? */
+    abstract accepts(scope: string | undefined, kind: string | undefined): boolean;
+    /** @internal */
+    abstract handle(message: ChannelIncomingMessage): Promise<ChannelOutcome>;
+    /** @internal */
+    applyJoined(): void;
+    /** @internal */
+    applyLeft(): void;
+    /** @internal */
+    applyPeers(peers: ChannelPeer[]): void;
+    /** @internal */
+    applyPeerJoined(peer: ChannelPeer): void;
+    /** @internal */
+    applyPeerLeft(from: string): void;
+    /** @internal */
+    failPending(error: Error): boolean;
+    protected post(message: Record<string, unknown>): void;
+}
+/**
+ * The collaboration room: every user's tab of this app that joined it, across
+ * accounts. Messages here are events — nobody replies.
+ *
+ * `E` maps each event name to its payload, so `send` and `on` are checked.
+ */
+export declare class CollabRoom<E extends object = AnyChannelEvents> extends ChannelRoom {
+    #private;
+    /** @internal Use `client.channel.collab()`. */
+    constructor(transport: ChannelTransport);
+    /**
+     * Listens for an event other tabs send. Any number of listeners per event.
+     * @returns a function that removes the listener.
+     */
+    on<K extends keyof E & string>(type: K, listener: (payload: E[K], meta: ChannelMessageMeta) => void): () => void;
+    /**
+     * Sends an event to the other tabs in the room. Does nothing while this tab
+     * is not in it, matching what the platform does with a message from outside.
+     */
+    send<K extends keyof E & string>(type: K, payload: E[K]): void;
+    accepts(scope: string | undefined): boolean;
+    handle(message: ChannelIncomingMessage): Promise<ChannelOutcome>;
+}
+/**
+ * Commands from this account's external tools — a CLI, an MCP server, a Revit
+ * plugin — of one `kind`, or of every kind when none is given.
+ *
+ * `C` maps each command name to `{ payload, reply }`, so a handler's argument
+ * and return value are checked. A command without `reply` is a notification.
+ */
+export declare class ExternalRoom<C extends {
+    [K in keyof C]: ChannelCommandShape;
+} = AnyChannelCommands> extends ChannelRoom {
+    #private;
+    readonly kind?: string | undefined;
+    /** @internal Use `client.channel.external(kind)`. */
+    constructor(transport: ChannelTransport, kind?: string | undefined);
+    /**
+     * Handles a command. When the sender asked for an answer, what you return
+     * is sent back to it; if you throw, it gets an error instead of waiting for
+     * a timeout. When it did not ask (a notification), the return value is
+     * ignored.
+     *
+     * One handler per command: a second one for the same name throws, since two
+     * would both try to answer.
+     * @returns a function that removes the handler.
+     */
+    on<K extends keyof C & string>(type: K, handler: (payload: PayloadOf<C[K]>, meta: ChannelMessageMeta) => ReplyOf<C[K]> | Promise<ReplyOf<C[K]>>): () => void;
+    accepts(scope: string | undefined, kind: string | undefined): boolean;
+    /** @internal Whether this room has any handler at all. */
+    get hasHandlers(): boolean;
+    handle(message: ChannelIncomingMessage): Promise<ChannelOutcome>;
+}
+/**
+ * Typed access to the platform channel from inside an app: a collaboration
+ * room shared with other users, and rooms for commands from external tools.
+ * Reach it as `client.channel`.
+ *
+ * @example
+ * ```ts
+ * type McpCommands = {
+ *   'select-by-category': { payload: { category: string }; reply: { count: number } };
+ * };
+ *
+ * const mcp = client.channel.external<McpCommands>('mcp');
+ * mcp.on('select-by-category', async ({ category }) => ({
+ *   count: await selectByCategory(category),
+ * }));
+ * await mcp.join();
+ * ```
+ */
+export declare class ChannelClient {
+    #private;
+    constructor(transport: ChannelTransport);
+    /** The collaboration room for this app. Always the same instance. */
+    collab<E extends object = AnyChannelEvents>(): CollabRoom<E>;
+    /**
+     * The room for commands from this account's external tools of one `kind`
+     * (`'mcp'`, `'cli'`, `'revit'`…), or from any of them when `kind` is omitted.
+     * Always the same instance for the same kind.
+     */
+    external<C extends {
+        [K in keyof C]: ChannelCommandShape;
+    } = AnyChannelCommands>(kind?: string): ExternalRoom<C>;
+    /** Stops listening. For tests and teardown; an app normally never calls it. */
+    dispose(): void;
+}
+export {};

package/dist/core/channel.test.d.ts

@@ -0,0 +1,7 @@
+import { ChannelClient } from './channel';
+
+/**
+ * Compile-time checks. Nothing here runs: it exists so `tsc` fails if the
+ * types stop rejecting what they are meant to reject.
+ */
+export declare function typeChecks(channel: ChannelClient): void;

package/dist/core/examples/channel.d.ts

@@ -0,0 +1,31 @@
+import { PlatformClient } from '../platform-client';
+
+type McpCommands = {
+    'select-by-category': {
+        payload: {
+            category: string;
+        };
+        reply: {
+            count: number;
+        };
+    };
+    'get-loaded-models': {
+        payload: undefined;
+        reply: {
+            models: string[];
+        };
+    };
+};
+type CollabEvents = {
+    'cursor-position': {
+        userName: string;
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+export declare function setupChannel(client: PlatformClient): Promise<{
+    mcp: import('../channel').ExternalRoom<McpCommands>;
+    collab: import('../channel').CollabRoom<CollabEvents>;
+}>;
+export {};

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

@@ -1,5 +1,6 @@
 import { EngineServicesClient, EngineServicesClientProps } from './client';
 import { Project, ProjectData } from '../types/projects';
+import { ChannelClient } from './channel';
 import { MarkNotificationsReadResultDto, NotificationPageDto, NotificationSubscriptionView } from '../types/notifications';
 
 /**
@@ -103,6 +104,31 @@ export declare class PlatformClient extends EngineServicesClient {
      * carries a fresh JWT on every navigation.
      */
     static fromPlatformContext(props?: Omit<EngineServicesClientProps, 'useBearer'>): PlatformClient;
+    /**
+     * The platform channel, from inside an app: a collaboration room shared with
+     * other users of the app, and rooms for commands from external tools (a CLI,
+     * an MCP server, a Revit plugin). Typed, and built on the `postMessage`
+     * contract with the platform shell — the app never opens a socket.
+     *
+     * Only available in an app running in the platform's iframe; reading it
+     * anywhere else throws. Created on first use.
+     *
+     * @example
+     * ```ts
+     * type McpCommands = {
+     *   'select-by-category': { payload: { category: string }; reply: { count: number } };
+     * };
+     *
+     * const mcp = client.channel.external<McpCommands>('mcp');
+     * mcp.on('select-by-category', async ({ category }) => ({ count: 3 }));
+     * await mcp.join();
+     *
+     * const collab = client.channel.collab();
+     * collab.onPeerLeft(({ from }) => removeAvatar(from));
+     * await collab.join();
+     * ```
+     */
+    get channel(): ChannelClient;
     /**
      * Gets a project by ID. JWT-only — lives here because
      * `GET /project/:id` is guarded by `AccountActiveGuard + ProjectAccessGuard`.