@thatopen/services 0.8.0 → 0.9.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

@@ -1133,7 +1133,7 @@ export type ContextMode = "default" | "hidden";
 /** The three kinds of change a commit can carry. */
 export type ChangeKind = "create" | "update" | "delete";
 /**
- * Stable id for a commit across models — which is now just its guid.
+ * Stable id for a commit across models — which is now just its guid.
  *
  * It used to have to be `${model}:${id}`, because the id was a per-model version number and every
  * model had a commit 3. A guid needs no help being unique, and that is exactly what it was for.
@@ -1146,25 +1146,25 @@ export declare const commitKey: (c: {
 }) => string;
 /** How the commit is shown in 3D: review colours, or the model as it ended up. */
 export type HighlightMode = "colored" | "plain";
-/** Dominant change type of a commit: delete → create → update. */
+/** Dominant change type of a commit: delete → create → update. */
 export declare function dominantChange(commit: RevitFlowCommit): DominantChange;
 /**
- * GitHistoryManager — headless engine for the revit-flow git-history built-in.
+ * GitHistoryManager — headless engine for the revit-flow git-history built-in.
  *
- * Owns ALL viewer mutation for the change outlines. It does NOT load the model —
+ * Owns ALL viewer mutation for the change outlines. It does NOT load the model —
  * the user opens a model from the Project Files panel, and this manager reacts to
  * that load: it reads the model's hidden `revitflow_history.json` (if any) and
  * publishes the commit list. Showing a commit outlines its changed elements
- * (create → green, update → blue, delete → red) via three independently-colored
- * `OBF.Outliner` groups — a cheap post-process outline that never recolors the
+ * (create → green, update → blue, delete → red) via three independently-colored
+ * `OBF.Outliner` groups — a cheap post-process outline that never recolors the
  * fragment geometry. The Lit panel (`top-git-history`) is intent-only: it calls
  * these methods and subscribes to the events below.
  *
  * Data model, per loaded model (fileId == modelId), all HIDDEN children of it:
- *   - revitflow_history.json — { model, commits: [{ id, parent, author, source,
+ *   - revitflow_history.json — { model, commits: [{ id, parent, author, source,
  *       timestamp, changes:[{type,uniqueId}], counts }] }. The first commit is the
  *       INITIAL full-model capture (its geometry == the visible baseline file).
- *   - revitflow_frag_<N>.frag — delta fragments for commit N (its created+modified
+ *   - revitflow_frag_<N>.frag — delta fragments for commit N (its created+modified
  *       geometry), loaded on demand so created elements can be colored.
  */
 declare class _GitHistoryManager extends OBC.Component {
@@ -1177,15 +1177,40 @@ declare class _GitHistoryManager extends OBC.Component {
     readonly onError: OBC.Event<string>;
     /** The GUID currently selected in the 3D view (null when the selection is cleared). */
     readonly onSelectedGuidChanged: OBC.Event<string | null>;
+    /** A source icon was added or replaced. */
+    readonly onSourceIconsChanged: OBC.Event<void>;
+    /**
+     * Which mark to draw on a commit, by the application that wrote it.
+     *
+     * Every commit already says who made it, in `source`. The panel used to draw the Revit logo on
+     * all of them regardless, which was true while Revit was the only thing that could write one and
+     * became a lie the moment anything else did: a commit from another tool would claim to be a
+     * Revit commit, on the one part of the row whose whole job is to say where a change came from.
+     *
+     * The format is deliberately open about who writes history, so the icons have to be too. This is
+     * the registry. Only `revit` is built in; an application adds its own:
+     *
+     *   const history = components.get(GitHistoryManager);
+     *   history.setSourceIcon("rhino", "https://…/rhino.svg");   // a URL, or a data: URI
+     *   history.setSourceIcon("tekla", "<svg viewBox='0 0 24 24'>…</svg>");   // or the markup
+     *
+     * A source with no icon gets a neutral one rather than somebody else's.
+     */
+    readonly sourceIcons: Map<string, string>;
+    /**
+     * @param source the commit's own `source` value, matched case-insensitively.
+     * @param icon a URL, a `data:` URI, or inline `<svg>` markup.
+     */
+    setSourceIcon(source: string, icon: string): void;
     world?: OBC.World;
     /**
      * What happens to elements that are NOT part of the selected commit:
-     *   "default" — left as they are (the change outlines sit on the full model)
-     *   "hidden"  — hidden entirely, isolating the commit's elements
+     *   "default" — left as they are (the change outlines sit on the full model)
+     *   "hidden"  — hidden entirely, isolating the commit's elements
      *
      * A dimmed ("ghost") middle ground was dropped: the fragments x-ray writes depth
      * from the pixels its screen door keeps, so dimmed geometry still occluded the very
-     * elements under review — worse the denser the model in front. Fixing that properly
+     * elements under review — worse the denser the model in front. Fixing that properly
      * belongs in the renderer, not here, so this offers the two states that are exact.
      */
     contextMode: ContextMode;
@@ -1203,18 +1228,18 @@ declare class _GitHistoryManager extends OBC.Component {
     prefetchRadius: number;
     /**
      * How a commit is presented in 3D:
-     *   "colored" — outline created/edited/deleted in their colours (the review lens)
-     *   "plain"   — no outlines: the model simply as it stood AFTER the commit, so the
+     *   "colored" — outline created/edited/deleted in their colours (the review lens)
+     *   "plain"   — no outlines: the model simply as it stood AFTER the commit, so the
      *               deleted elements are hidden rather than painted red
      */
     highlightMode: HighlightMode;
-    /** @deprecated kept so older callers still compile — maps onto contextMode. */
+    /** @deprecated kept so older callers still compile — maps onto contextMode. */
     get isolateChanges(): boolean;
-    /** Green — created elements. */
+    /** Green — created elements. */
     readonly COLOR_CREATED = "#22c55e";
-    /** Golden yellow — modified elements. */
+    /** Golden yellow — modified elements. */
     readonly COLOR_MODIFIED = "#e3b341";
-    /** Red — deleted elements. */
+    /** Red — deleted elements. */
     readonly COLOR_DELETED = "#ef4444";
     readonly GROUP_CREATED = "revitflow-created";
     readonly GROUP_MODIFIED = "revitflow-modified";
@@ -1223,7 +1248,7 @@ declare class _GitHistoryManager extends OBC.Component {
     private _projectId?;
     /**
      * One entry per loaded revit-flow model. Commit ids are per-model version numbers, so
-     * they collide across models — every commit is tagged with its modelId and a commit is
+     * they collide across models — every commit is tagged with its modelId and a commit is
      * addressed by {@link commitKey}, never by id alone.
      */
     private _models;
@@ -1295,7 +1320,7 @@ declare class _GitHistoryManager extends OBC.Component {
     init(client: PlatformClient): Promise<void>;
     /**
      * Follow the viewer's selection so the element view tracks whatever the user clicks in
-     * 3D — no "trace this" button to press. The Highlighter's events appear asynchronously
+     * 3D — no "trace this" button to press. The Highlighter's events appear asynchronously
      * (they're registered when the viewer sets it up), so retry briefly until they exist.
      */
     private _watchSelection;
@@ -1304,7 +1329,7 @@ declare class _GitHistoryManager extends OBC.Component {
     /**
      * Probe a loaded model for a sibling visible `revitflow_history.json` in its
      * folder. If present, adopt it as the active model and publish its commits.
-     * Silent for non-revit models and for our own delta frags — only genuine
+     * Silent for non-revit models and for our own delta frags — only genuine
      * fetch/parse failures raise onError.
      */
     private _probeModel;
@@ -1339,7 +1364,7 @@ declare class _GitHistoryManager extends OBC.Component {
      * Show the model as it stood AT `commit`: the visible baseline is the model at its
      * INITIAL commit, and everything created later lives in per-commit delta .frags loaded
      * as separate models. Those deltas stay loaded (the prefetch window keeps neighbours
-     * warm), so stepping BACK has to hide the ones from later commits — otherwise a wall
+     * warm), so stepping BACK has to hide the ones from later commits — otherwise a wall
      * added in commit 3 was still sitting there while you were looking at commit 2.
      * Only touches deltas of the commit's own model; other models keep their own state.
      */
@@ -1379,7 +1404,7 @@ declare class _GitHistoryManager extends OBC.Component {
     selectedGuids(): Promise<string[]>;
     selectedGuid(): Promise<string | null>;
     /**
-     * Select every element the commit touched, in the viewer's own selection — so the
+     * Select every element the commit touched, in the viewer's own selection — so the
      * usual tools (properties, isolate, zoom) work on it like any hand-made selection.
      * Honours the current type filter, so "only deletions" selects only those.
      * @returns how many elements ended up selected.
@@ -1393,11 +1418,11 @@ declare class _GitHistoryManager extends OBC.Component {
     private _outliner;
     /**
      * Create the three independently-colored outline groups once. The viewer
-     * owns the Outliner's DEFAULT group (selection) — we only add our own named
+     * owns the Outliner's DEFAULT group (selection) — we only add our own named
      * groups and never touch "default".
      */
     private _ensureGroups;
-    /** Clear our three outline groups only — leaves the viewer's default group. */
+    /** Clear our three outline groups only — leaves the viewer's default group. */
     private _clearOutlines;
     /**
      * Resolve each change bucket's GUIDs to localIds across every loaded model
@@ -1411,7 +1436,7 @@ declare class _GitHistoryManager extends OBC.Component {
     private _dropSuperseded;
     /**
      * Hide (or restore) the elements a commit deleted. Tracked separately from the context
-     * modes so switching Colored↔Plain doesn't disturb ghosting or the rest of the model.
+     * modes so switching Colored↔Plain doesn't disturb ghosting or the rest of the model.
      */
     private _applyDeletedVisibility;
     /**
@@ -1420,14 +1445,14 @@ declare class _GitHistoryManager extends OBC.Component {
      * THE BUG THIS EXISTS FOR. The baseline .frag holds the whole model as of the first
      * commit, and every later commit ships a delta .frag with the geometry it created AND
      * the geometry it modified. Both stay in the scene. For a CREATED element that is
-     * right — it exists in exactly one place. For a MODIFIED one it is not: the element is
+     * right — it exists in exactly one place. For a MODIFIED one it is not: the element is
      * in the baseline at its old shape and in the delta at its new one, and the viewer drew
      * both. Measured 2026-08-05 on a wall whose height Quim raised: the new wall stood
      * proud of the old one, with the coincident faces z-fighting into a dotted band.
      *
      * The rule is the obvious one once stated: for any element, only the newest VISIBLE
      * source may draw it. Deltas are walked newest-first, each guid is claimed by the first
-     * source that has it, and every older copy — in an older delta or in the baseline — is
+     * source that has it, and every older copy — in an older delta or in the baseline — is
      * hidden. Deltas newer than the commit being shown are already hidden wholesale by
      * `_applyFutureVisibility`, so they never get to claim anything.
      *
@@ -1445,13 +1470,13 @@ declare class _GitHistoryManager extends OBC.Component {
      * load that commit's delta, which is the last place its geometry existed.
      */
     private _ensureDeletedGeometry;
-    /** GUIDs → { modelId: Set<localId> } across the given models. */
+    /** GUIDs → { modelId: Set<localId> } across the given models. */
     private _buildMap;
     private _mergeMaps;
     /**
      * Dim ("ghost") or hide every element that is NOT part of the shown commit, per the
      * chosen context mode. Best-effort per model: a model that doesn't support the call is
-     * simply left alone — the outlines still convey the change.
+     * simply left alone — the outlines still convey the change.
      */
     private _applyContext;
     /** Undo whatever the context mode did: drop the ghost overlay and restore visibility. */
@@ -1469,42 +1494,42 @@ declare class _GitHistoryManager extends OBC.Component {
     private _firstWorld;
 }
 /**
- * GitHistoryManager — headless engine for the revit-flow git-history built-in.
+ * GitHistoryManager — headless engine for the revit-flow git-history built-in.
  *
- * Owns ALL viewer mutation for the change outlines. It does NOT load the model —
+ * Owns ALL viewer mutation for the change outlines. It does NOT load the model —
  * the user opens a model from the Project Files panel, and this manager reacts to
  * that load: it reads the model's hidden `revitflow_history.json` (if any) and
  * publishes the commit list. Showing a commit outlines its changed elements
- * (create → green, update → blue, delete → red) via three independently-colored
- * `OBF.Outliner` groups — a cheap post-process outline that never recolors the
+ * (create → green, update → blue, delete → red) via three independently-colored
+ * `OBF.Outliner` groups — a cheap post-process outline that never recolors the
  * fragment geometry. The Lit panel (`top-git-history`) is intent-only: it calls
  * these methods and subscribes to the events below.
  *
  * Data model, per loaded model (fileId == modelId), all HIDDEN children of it:
- *   - revitflow_history.json — { model, commits: [{ id, parent, author, source,
+ *   - revitflow_history.json — { model, commits: [{ id, parent, author, source,
  *       timestamp, changes:[{type,uniqueId}], counts }] }. The first commit is the
  *       INITIAL full-model capture (its geometry == the visible baseline file).
- *   - revitflow_frag_<N>.frag — delta fragments for commit N (its created+modified
+ *   - revitflow_frag_<N>.frag — delta fragments for commit N (its created+modified
  *       geometry), loaded on demand so created elements can be colored.
  */
 export type GitHistoryManager = InstanceType<typeof _GitHistoryManager>;
 /**
- * GitHistoryManager — headless engine for the revit-flow git-history built-in.
+ * GitHistoryManager — headless engine for the revit-flow git-history built-in.
  *
- * Owns ALL viewer mutation for the change outlines. It does NOT load the model —
+ * Owns ALL viewer mutation for the change outlines. It does NOT load the model —
  * the user opens a model from the Project Files panel, and this manager reacts to
  * that load: it reads the model's hidden `revitflow_history.json` (if any) and
  * publishes the commit list. Showing a commit outlines its changed elements
- * (create → green, update → blue, delete → red) via three independently-colored
- * `OBF.Outliner` groups — a cheap post-process outline that never recolors the
+ * (create → green, update → blue, delete → red) via three independently-colored
+ * `OBF.Outliner` groups — a cheap post-process outline that never recolors the
  * fragment geometry. The Lit panel (`top-git-history`) is intent-only: it calls
  * these methods and subscribes to the events below.
  *
  * Data model, per loaded model (fileId == modelId), all HIDDEN children of it:
- *   - revitflow_history.json — { model, commits: [{ id, parent, author, source,
+ *   - revitflow_history.json — { model, commits: [{ id, parent, author, source,
  *       timestamp, changes:[{type,uniqueId}], counts }] }. The first commit is the
  *       INITIAL full-model capture (its geometry == the visible baseline file).
- *   - revitflow_frag_<N>.frag — delta fragments for commit N (its created+modified
+ *   - revitflow_frag_<N>.frag — delta fragments for commit N (its created+modified
  *       geometry), loaded on demand so created elements can be colored.
  */
 export declare const GitHistoryManager: typeof _GitHistoryManager & {

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]";
 }
@@ -6942,6 +6953,14 @@ class EngineServicesClient {
    * the new token is picked up on every request — expired tokens no
    * longer stick around.
    */
+  /**
+   * Socket origin without namespace or query, for gateways other than the
+   * execution one. `wsUrl` already carries a token that may be stale when a
+   * provider is in play, so callers append their own.
+   */
+  get socketOrigin() {
+    return this.wsUrl.split("?")[0];
+  }
   async resolveAccessToken() {
     return this.accessToken;
   }
@@ -8226,7 +8245,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

@@ -207,6 +207,12 @@ export declare class EngineServicesClient {
      * the new token is picked up on every request — expired tokens no
      * longer stick around.
      */
+    /**
+     * Socket origin without namespace or query, for gateways other than the
+     * execution one. `wsUrl` already carries a token that may be stale when a
+     * provider is in play, so callers append their own.
+     */
+    protected get socketOrigin(): string;
     protected resolveAccessToken(): Promise<string>;
     /**
      * Protected extension hook for subclasses (e.g. `PlatformClient`) that

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

@@ -1,6 +1,33 @@
 import { EngineServicesClient, EngineServicesClientProps } from './client';
 import { Project, ProjectData } from '../types/projects';
+import { MarkNotificationsReadResultDto, NotificationPageDto, NotificationSubscriptionView } from '../types/notifications';
 
+/**
+ * What arrived on the socket. One callback for all three because a bell
+ * reacts the same way to each: refresh the badge, and the list if open.
+ *
+ * `allRead` is one event for the whole sweep rather than one per
+ * notification, so do not expect an id on it.
+ */
+export type LiveNotificationEvent = {
+    type: 'created';
+    id: string;
+} | {
+    type: 'read';
+    id: string;
+} | {
+    type: 'allRead';
+    batch: number;
+};
+/** Per-automation opt-in. `failures` skips started events entirely. */
+export type NotificationSubscriptionFilterInput = 'all' | 'failures';
+export interface NotificationSubscriptionInput {
+    filter?: NotificationSubscriptionFilterInput;
+    /** Overrides the account-level channel setting for this automation only. */
+    channels?: {
+        email?: boolean;
+    };
+}
 /** Scope by which a permission was granted (or `'none'` if denied). */
 export type PermissionScope = 'global' | 'project' | 'entity' | 'none';
 /** Result of a single permission check. */
@@ -110,4 +137,116 @@ export declare class PlatformClient extends EngineServicesClient {
      * single round-trip; results come back in the same order as `checks`.
      */
     checkPermissionBatch(checks: PermissionCheckEntry[]): Promise<PermissionCheckResult[]>;
+    /**
+     * Lists the signed-in user's notifications, newest first.
+     *
+     * Scoped to whoever the bearer token belongs to — an app cannot read
+     * anyone else's. Muted notifications are included: muting silences the
+     * badge and the delivery channels, it does not hide the record.
+     *
+     * Paginate by passing the previous response's `nextCursor` back in; it is
+     * opaque, so do not build one by hand. A null `nextCursor` means the last
+     * page.
+     *
+     * @example Walk every page:
+     * ```ts
+     * let cursor: string | undefined;
+     * do {
+     *   const page = await client.getNotifications({ cursor });
+     *   render(page.items);
+     *   cursor = page.nextCursor ?? undefined;
+     * } while (cursor);
+     * ```
+     */
+    getNotifications(params?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<NotificationPageDto>;
+    /**
+     * Number of unread notifications, excluding muted ones. This is the bell
+     * badge count, so it is cheap to poll.
+     */
+    getUnreadNotificationCount(): Promise<number>;
+    /**
+     * Marks specific notifications as read. Ids the caller does not own are
+     * ignored rather than rejected, so `updated` can be lower than the number
+     * passed in.
+     */
+    markNotificationsRead(notificationIds: string[]): Promise<MarkNotificationsReadResultDto>;
+    /** Marks every unread notification as read in one call. */
+    markAllNotificationsRead(): Promise<MarkNotificationsReadResultDto>;
+    /**
+     * The automations this user has subscribed to. Nobody is subscribed by
+     * default, so an empty list is the normal state.
+     */
+    getNotificationSubscriptions(): Promise<NotificationSubscriptionView[]>;
+    /**
+     * Removes this user's subscription to one automation.
+     *
+     * Unlike subscribing, which happens through the project routes, this works
+     * for any automation the user is subscribed to and keeps working after the
+     * automation itself is gone — opting out must never be the thing that
+     * fails.
+     */
+    unsubscribeFromAutomation(hookId: string): Promise<{
+        unsubscribed: boolean;
+    }>;
+    /**
+     * Subscribes the signed-in user to one project automation's runs.
+     *
+     * Nobody is subscribed by default, so this is what makes an automation
+     * produce notifications for this user at all. Subscribing again is
+     * harmless: it updates the existing subscription rather than duplicating.
+     *
+     * Read-level access to the project is enough. Someone who can see an
+     * automation can follow it without being able to change it.
+     *
+     * @example Follow only the failures, and email me about them:
+     * ```ts
+     * await client.subscribeToAutomation(projectId, hookId, {
+     *   filter: 'failures',
+     *   channels: { email: true },
+     * });
+     * ```
+     */
+    subscribeToAutomation(projectId: string, hookId: string, input?: NotificationSubscriptionInput): Promise<{
+        subscribed: true;
+    }>;
+    /**
+     * Changes an existing subscription. Only the fields passed are touched, so
+     * sending `channels` alone leaves the filter as it was.
+     *
+     * Throws if the user is not subscribed; use {@link subscribeToAutomation}
+     * to create one.
+     */
+    updateAutomationSubscription(projectId: string, hookId: string, changes: NotificationSubscriptionInput): Promise<{
+        updated: true;
+    }>;
+    /**
+     * Listens for this user's notifications in real time.
+     *
+     * Unlike {@link EngineServicesClient.onExecutionProgress}, which follows one
+     * execution and closes when it ends, this stays connected for the session:
+     * the server puts the socket in a room for the signed-in account and pushes
+     * anything addressed to them.
+     *
+     * The events carry ids rather than the notifications themselves, so treat
+     * them as a signal to refresh. That keeps a burst cheap and means the
+     * server is never the source of a stale render.
+     *
+     * Requires a user JWT. An API access token is rejected by the gateway,
+     * because it identifies a token rather than a person.
+     *
+     * @returns a function that disconnects. Call it on unmount.
+     *
+     * @example
+     * ```ts
+     * const stop = await client.onNotification((event) => {
+     *   if (event.type === 'created') refreshBell();
+     * });
+     * // later
+     * stop();
+     * ```
+     */
+    onNotification(onEvent: (event: LiveNotificationEvent) => void): Promise<() => void>;
 }