@thatopen/services 0.10.0 → 0.12.0

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

@@ -1567,6 +1567,238 @@ export type HelloWorld = InstanceType<typeof _HelloWorld>;
 export declare const HelloWorld: typeof _HelloWorld & {
     uuid: "2c4ae432-fc24-43e9-9783-0c960c674e96";
 };
+export type ProjectNamespaceKey = "origin" | "georeferencing" | "appSettings";
+export interface ProjectNamespace {
+    label: string;
+    description?: string;
+}
+export interface ProjectEntity<T = unknown> {
+    namespaceId: ProjectNamespaceKey;
+    label: string;
+    description?: string;
+    data: T;
+}
+/** GIS origin point that fixes the scene's (0,0,0) to a real-world coordinate. */
+export interface OriginData {
+    lat: number;
+    lon: number;
+    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>;
+}
+export type AssetCoordinateType = "splat" | "ifc" | "point-cloud" | (string & {});
+export interface AssetCoordinate {
+    fileId: string;
+    type: AssetCoordinateType;
+    lat: number;
+    lon: number;
+    height: number;
+    rotation: number;
+}
+export interface GraphicsSettingsData {
+    stylePreset: string;
+    postproduction: boolean;
+    edges: {
+        enabled: boolean;
+        color: string;
+        opacity: number;
+    };
+    ambientOcclusion: {
+        enabled: boolean;
+        value: number;
+    };
+    tonalShading: {
+        enabled: boolean;
+        value: number;
+    };
+    surfaceColor: {
+        enabled: boolean;
+    };
+    transparentBackground: {
+        enabled: boolean;
+        color: string;
+    };
+    grid: {
+        enabled: boolean;
+        color: string;
+    };
+    gridHeight: {
+        auto: boolean;
+        value: number;
+    };
+    antiAliasing: boolean;
+    nativeResolution: boolean;
+    adaptiveResolution: {
+        enabled: boolean;
+        value: number;
+    };
+    minResolution: number;
+    renderScale: number;
+}
+export interface ProjectManagerData {
+    schemaVersion: 1;
+    namespaces: Record<ProjectNamespaceKey, ProjectNamespace>;
+    entities: {
+        origin: ProjectEntity<OriginData>;
+        bimCoordinates: ProjectEntity<BimCoordinatesData>;
+        assetCoordinates: ProjectEntity<AssetCoordinate[]>;
+        graphicsSettings: ProjectEntity<GraphicsSettingsData>;
+    };
+}
+export interface SingletonEntity<T> {
+    get(): T | undefined;
+    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>;
+}
+export interface AssetCoordinatesEntity {
+    getAll(): AssetCoordinate[];
+    get(fileId: string): AssetCoordinate | undefined;
+    getByType(type: AssetCoordinateType): AssetCoordinate[];
+    set(fileId: string, data: Omit<AssetCoordinate, "fileId">): Promise<void>;
+    remove(fileId: string): Promise<void>;
+}
+/**
+ * ProjectManager is the platform's canonical store for project-level
+ * configuration and data — origin/georeferencing/app-settings today, with
+ * room to grow. It persists a single JSON file (`${ProjectManager.uuid}.json`)
+ * loose directly inside `__project_data` (same folder convention `GISManager`
+ * already used) — NOT in a per-app subfolder like `collider`/`cde`, which are
+ * for secondary, per-builtin data. Sharing that root folder with other
+ * builtins doesn't change its role: it's still the one canonical project
+ * record, meant to stop each builtin from inventing its own ad-hoc
+ * project-persistence pattern.
+ *
+ * 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.
+ * - `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";
+    enabled: boolean;
+    /** True once init(client) has been called — safe to use the entity accessors. */
+    get ready(): boolean;
+    /** Suppress auto-save while bulk-loading data. */
+    private _loadingData;
+    readonly onSaveStart: OBC.Event<void>;
+    readonly onSaveComplete: OBC.Event<boolean>;
+    private _client?;
+    private _fileId?;
+    private _data;
+    private _saveTimer?;
+    private _savePromise?;
+    private _scheduleSave;
+    private _queueSave;
+    private _doSave;
+    /** Cancels the pending debounce and runs the save immediately. 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>;
+    graphicsSettings: SingletonEntity<GraphicsSettingsData>;
+    bimCoordinates: BimCoordinatesEntity;
+    assetCoordinates: AssetCoordinatesEntity;
+    getNamespaces(): Record<ProjectNamespaceKey, ProjectNamespace>;
+    getNamespace(key: ProjectNamespaceKey): Record<string, unknown>;
+}
+/**
+ * ProjectManager is the platform's canonical store for project-level
+ * configuration and data — origin/georeferencing/app-settings today, with
+ * room to grow. It persists a single JSON file (`${ProjectManager.uuid}.json`)
+ * loose directly inside `__project_data` (same folder convention `GISManager`
+ * already used) — NOT in a per-app subfolder like `collider`/`cde`, which are
+ * for secondary, per-builtin data. Sharing that root folder with other
+ * builtins doesn't change its role: it's still the one canonical project
+ * record, meant to stop each builtin from inventing its own ad-hoc
+ * project-persistence pattern.
+ *
+ * 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.
+ * - `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>;
+/**
+ * ProjectManager is the platform's canonical store for project-level
+ * configuration and data — origin/georeferencing/app-settings today, with
+ * room to grow. It persists a single JSON file (`${ProjectManager.uuid}.json`)
+ * loose directly inside `__project_data` (same folder convention `GISManager`
+ * already used) — NOT in a per-app subfolder like `collider`/`cde`, which are
+ * for secondary, per-builtin data. Sharing that root folder with other
+ * builtins doesn't change its role: it's still the one canonical project
+ * record, meant to stop each builtin from inventing its own ad-hoc
+ * project-persistence pattern.
+ *
+ * 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.
+ * - `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";
+};
 /** `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. */

package/dist/cli.js

@@ -6811,12 +6811,22 @@ function parseErrorBody(body) {
   }
   return {};
 }
+function retryAfterFromDetails(details) {
+  if (!details || typeof details !== "object") return void 0;
+  const value2 = details.retryAfter;
+  return typeof value2 === "number" && Number.isFinite(value2) && value2 >= 0 ? value2 : void 0;
+}
 class RequestError extends Error {
   status;
   code;
   details;
   body;
-  constructor(status, statusText, body) {
+  /**
+   * Seconds to wait before retrying, taken from the `Retry-After` header or
+   * from `details.retryAfter`. Only present on rate-limited (429) responses.
+   */
+  retryAfter;
+  constructor(status, statusText, body, retryAfter) {
     const parsed = parseErrorBody(body);
     super(parsed.message ?? `${statusText || "Request failed"} (${status})`);
     this.name = "RequestError";
@@ -6824,6 +6834,7 @@ class RequestError extends Error {
     this.code = parsed.code;
     this.details = parsed.details;
     this.body = body;
+    this.retryAfter = retryAfter ?? retryAfterFromDetails(parsed.details);
   }
 }
 const FOLDER_PATH = "item/folder";
@@ -6834,6 +6845,35 @@ const HIDDEN_PATH = "hidden";
 const ITEM_TYPE_FILE = "FILE";
 const ITEM_TYPE_COMPONENT = "TOOL";
 const ITEM_TYPE_APP = "APP";
+const RETRY_BASE_DELAY_MS = 500;
+const RETRY_MAX_DELAY_MS = 3e4;
+const RETRY_JITTER_RATIO = 0.25;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function parseRetryAfter(response) {
+  const raw = response.headers?.get?.("Retry-After");
+  if (!raw) return void 0;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds);
+  const timestamp = Date.parse(raw);
+  if (Number.isNaN(timestamp)) return void 0;
+  return Math.max(0, (timestamp - Date.now()) / 1e3);
+}
+function isRetryable(error2) {
+  if (!(error2 instanceof RequestError)) return true;
+  return error2.status === 429 || error2.status >= 500;
+}
+function retryDelayMs(error2, attempt) {
+  const backoff = Math.min(
+    RETRY_BASE_DELAY_MS * 2 ** attempt,
+    RETRY_MAX_DELAY_MS
+  );
+  const jitter = backoff * RETRY_JITTER_RATIO * Math.random();
+  const serverDelay = error2 instanceof RequestError && error2.retryAfter != null ? error2.retryAfter * 1e3 : void 0;
+  if (serverDelay != null) {
+    return Math.min(serverDelay, RETRY_MAX_DELAY_MS) + jitter;
+  }
+  return backoff + jitter;
+}
 class EngineServicesClient {
   apiUrl;
   accessToken;
@@ -6906,7 +6946,9 @@ class EngineServicesClient {
     }
   }
   /**
-   * Sets the number of automatic retries for failed requests.
+   * Sets the number of automatic retries for failed requests. Retries use
+   * exponential backoff with jitter and honour `Retry-After`; only network
+   * failures, 429s and 5xx are retried.
    * @param retries - Number of retries (0 = no retries).
    */
   setRetries(retries) {
@@ -6966,7 +7008,7 @@ class EngineServicesClient {
     return this.accessToken;
   }
   async #requestApi(method, path2, requestData) {
-    const { body, query, contentType, retries, responseType } = requestData || {};
+    const { body, query, contentType, retries, responseType, retryAttempt } = requestData || {};
     const url2 = this.#buildUrl(path2);
     const cleanQuery = this.#cleanData(query);
     const token = await this.resolveAccessToken();
@@ -6992,7 +7034,8 @@ class EngineServicesClient {
         throw new RequestError(
           response.status,
           response.statusText,
-          textResponse
+          textResponse,
+          parseRetryAfter(response)
         );
       }
       if (responseType === "blob") {
@@ -7000,16 +7043,17 @@ class EngineServicesClient {
       }
       return response.json().then((data) => data).catch(() => void 0);
     } catch (e) {
-      let retriesAmmount = retries != null ? retries : this.retries;
-      if (retriesAmmount) {
-        retriesAmmount = retriesAmmount - 1;
+      const retriesLeft = retries != null ? retries : this.retries;
+      if (retriesLeft > 0 && isRetryable(e)) {
+        const attempt = retryAttempt ?? 0;
+        await sleep(retryDelayMs(e, attempt));
         return await this.#requestApi(method, path2, {
           ...requestData,
-          retries: retriesAmmount
+          retries: retriesLeft - 1,
+          retryAttempt: attempt + 1
         });
-      } else {
-        throw e;
       }
+      throw e;
     }
   }
   /**

package/dist/core/client.d.ts

@@ -84,7 +84,13 @@ export type DownloadItemFileParams = {
 };
 /** Configuration options for the {@link EngineServicesClient} constructor. */
 export type EngineServicesClientProps = {
-    /** Number of automatic retries on request failure. Default: 0. */
+    /**
+     * Number of automatic retries on request failure. Default: 0.
+     *
+     * Retries are spaced with exponential backoff plus jitter, and honour the
+     * server's `Retry-After` when it sends one. Only network failures, 429s and
+     * 5xx are retried — other 4xx fail immediately.
+     */
     retries?: number;
     /**
      * If true, sends the token as an `Authorization: Bearer` header instead of
@@ -167,7 +173,9 @@ export declare class EngineServicesClient {
      */
     constructor(accessToken: string, apiUrl: string, props?: EngineServicesClientProps);
     /**
-     * Sets the number of automatic retries for failed requests.
+     * Sets the number of automatic retries for failed requests. Retries use
+     * exponential backoff with jitter and honour `Retry-After`; only network
+     * failures, 429s and 5xx are retried.
      * @param retries - Number of retries (0 = no retries).
      */
     setRetries(retries: number): void;

package/dist/core/request-error.d.ts

@@ -15,11 +15,27 @@
  *   }
  * }
  * ```
+ *
+ * @example Rate limiting
+ * ```ts
+ * catch (err) {
+ *   if (err instanceof RequestError && err.status === 429) {
+ *     console.log(err.code);       // "RATE_LIMITED"
+ *     console.log(err.details);    // { limit, windowSeconds, retryAfter, scope }
+ *     console.log(err.retryAfter); // seconds to wait before trying again
+ *   }
+ * }
+ * ```
  */
 export declare class RequestError extends Error {
     readonly status: number;
     readonly code?: string;
     readonly details?: unknown;
     readonly body: string;
-    constructor(status: number, statusText: string, body: string);
+    /**
+     * Seconds to wait before retrying, taken from the `Retry-After` header or
+     * from `details.retryAfter`. Only present on rate-limited (429) responses.
+     */
+    readonly retryAfter?: number;
+    constructor(status: number, statusText: string, body: string, retryAfter?: number);
 }