@twinfinity/twin 6.1.0 → 6.1.2-ci.30738

package/src/errors.ts

@@ -1,4 +1,13 @@
-import type { TwinGet, AssetGet, TwinFileGet, AssetBatchResponse, AssetCategoryGet, AssetTypeGet } from './types';
+import type {
+    TwinGet,
+    AssetGet,
+    TwinFileGet,
+    AssetBatchResponse,
+    AssetCategoryGet,
+    AssetTypeGet,
+    TwinPrincipalPermissionsGet,
+    AssetPrincipalPermissionsGet
+} from './types';
 import type { AttachmentGet } from './types/asset-attachment-api';
 
 /**
@@ -43,6 +52,10 @@ export type TwinErrorCause =
     | 'StringIdInUse'
     | 'CatalogTooLarge'
     | 'EtagRequired'
+    | 'InvalidPaginationToken'
+    | 'SystemPrincipalImmutable'
+    | 'ManagePermissionsNotGrantableToAllAuthenticated'
+    | 'ValidationFailed'
     // Anything the server emits that this client doesn't know about yet.
     // (string & {}) keeps the autocomplete on the listed values above.
     // eslint-disable-next-line @typescript-eslint/ban-types
@@ -60,6 +73,10 @@ export type TwinErrorItemKind =
     | 'DocumentChange'
     | 'AssetCategory'
     | 'AssetType'
+    | 'Attachment'
+    | 'Document'
+    | 'Principal'
+    | 'Request'
     // eslint-disable-next-line @typescript-eslint/ban-types
     | (string & {});
 
@@ -68,7 +85,9 @@ export interface TwinErrorBody {
     cause: TwinErrorCause;
     item?: {
         kind: TwinErrorItemKind;
-        id: string;
+        // Absent when the reference names something that has no id — a `Request` kind
+        // carries only `field`, the request member that failed validation.
+        id?: string;
         version?: number;
         field?: string;
     };
@@ -87,8 +106,12 @@ export interface TwinErrorBody {
  * that switch on known causes will fall through to a default arm.
  */
 export async function readErrorBody(response: Response): Promise<TwinErrorBody> {
+    // Parse a clone, so that a body which turns out not to be JSON can still be read as text below.
+    // `json()` consumes the stream: on a real Response, reading the original here would leave the
+    // fallback unreachable and every non-JSON diagnostic would degrade to `statusText`.
+    const parseFrom = typeof response.clone === 'function' ? response.clone() : response;
     try {
-        const parsed = (await response.json()) as TwinErrorBody;
+        const parsed = (await parseFrom.json()) as TwinErrorBody;
         // Defensive shape check — JSON-but-not-our-shape (e.g. an upstream
         // ProblemDetails payload from a non-Twinfinity component) should still
         // surface usefully. `detail` is the only field every consumer reads.
@@ -121,9 +144,13 @@ export class TwinConflictError extends Error {
 }
 
 export class TwinNotFoundError extends Error {
-    constructor(message: string) {
+    /** The server's envelope, when there was one — `item.kind` names what was not found. */
+    public readonly errorBody?: TwinErrorBody;
+
+    constructor(message: string, errorBody?: TwinErrorBody) {
         super(message);
         this.name = 'TwinNotFoundError';
+        this.errorBody = errorBody;
     }
 }
 
@@ -377,3 +404,163 @@ export class TwinUnauthenticatedError extends Error {
         this.name = 'TwinUnauthenticatedError';
     }
 }
+
+// ---------- Twin-scoped permissions ----------
+
+/**
+ * The `cause` values the twin-scoped permission routes emit on a 409. A subset of
+ * `TwinConflictCause` in `backend/services/Twinfinity.Twin/Controllers/Model/TwinStatus.cs`:
+ * that enum's `GroupIdAlreadyInUse` and `ScopeIdAlreadyInUse` are raised by twin *creation*,
+ * which answers through {@link TwinConflictError}, never through this surface. Carries the same
+ * forward-compat tail as {@link TwinErrorCause}.
+ */
+export type TwinPermissionsConflictCause =
+    | 'EtagMismatch'
+    | 'EtagRequired'
+    | 'ScopesNotProvisioned'
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    | (string & {});
+
+/**
+ * The 409 envelope of the twin-scoped permission surface: the standard
+ * {@link TwinErrorBody} plus the server's view of the entry the caller lost a race on,
+ * whenever the service could report it.
+ */
+export interface TwinPermissionsConflictErrorBody extends TwinErrorBody {
+    cause: TwinPermissionsConflictCause;
+    currentState?: TwinPrincipalPermissionsGet;
+}
+
+/**
+ * Thrown by the twin permission mutation and listing methods on a 409.
+ *
+ * The three causes need different handling, which is why they are distinguishable
+ * rather than collapsed into one "modified by another user":
+ * - `EtagMismatch` — the etag is stale; re-read (or use {@link currentState}) and retry.
+ * - `EtagRequired` — the write omitted an etag but the principal already held an entry,
+ *   so it would have replaced state the caller never read. Retried by reading at all.
+ * - `ScopesNotProvisioned` — the twin owns no Twinfinity scope, so there is no permission
+ *   state to read or write. Nothing provisions on read, so retrying will not help.
+ */
+export class TwinPermissionsConflictError extends Error {
+    /**
+     * Which of the three conflicts this is. Named `conflictCause` rather than `cause` so the
+     * standard `Error.cause` — whose consumers expect a wrapped error, not a string — is left
+     * alone; the same value is on {@link errorBody}`.cause`.
+     */
+    public readonly conflictCause: TwinPermissionsConflictCause;
+    /** The entry as the server holds it, including the etag to retry with. */
+    public readonly currentState?: TwinPrincipalPermissionsGet;
+    public readonly errorBody: TwinPermissionsConflictErrorBody;
+
+    constructor(message: string, errorBody: TwinPermissionsConflictErrorBody) {
+        super(message);
+        this.name = 'TwinPermissionsConflictError';
+        this.conflictCause = errorBody.cause;
+        this.currentState = errorBody.currentState;
+        this.errorBody = errorBody;
+    }
+}
+
+/**
+ * Thrown on a 403 from the twin-scoped permission surface: the caller can see the twin
+ * but does not hold `ManageTwinPermissions` on it. Distinct from
+ * {@link TwinNotFoundError}, which is what a twin the caller cannot see at all answers —
+ * the surface refuses to confirm such a twin exists.
+ */
+export class TwinPermissionsForbiddenError extends Error {
+    /**
+     * The server's envelope, when there was one. Its presence is load-bearing: a genuine refusal
+     * carries `cause: 'InsufficientPermissions'`, while a Twin service that could not evaluate the
+     * request at all (a customer-database lookup that threw, a missing twin feature) falls through
+     * to the framework's default forbid handler and answers a 403 with no body. Without this a
+     * caller cannot tell "you may not" from "we could not tell", and would report the first.
+     */
+    public readonly errorBody?: TwinErrorBody;
+
+    constructor(message: string, errorBody?: TwinErrorBody) {
+        super(message);
+        this.name = 'TwinPermissionsForbiddenError';
+        this.errorBody = errorBody;
+    }
+}
+
+/**
+ * Thrown when a 404 names the principal rather than the twin — an id that no principal
+ * in the tenant carries, or one holding nothing on the twin for a `DELETE` to revoke.
+ */
+export class TwinPrincipalNotFoundError extends Error {
+    public readonly errorBody?: TwinErrorBody;
+
+    constructor(message: string, errorBody?: TwinErrorBody) {
+        super(message);
+        this.name = 'TwinPrincipalNotFoundError';
+        this.errorBody = errorBody;
+    }
+}
+
+/**
+ * Thrown on a 503: the Twin service could neither carry out the request nor answer it
+ * truthfully. The request is unchanged and safe to retry as-is — unlike
+ * {@link TwinPermissionsConflictError}, which never clears on its own.
+ */
+export class TwinTemporarilyUnavailableError extends Error {
+    public readonly errorBody?: TwinErrorBody;
+    /**
+     * The `Retry-After` the service sent, in seconds, when it sent one. The Twin service pairs the
+     * status with this header deliberately, so that "retrying is worthwhile" does not rest on the
+     * status alone — pass it to whatever backoff the caller uses instead of inventing a delay.
+     */
+    public readonly retryAfterSeconds?: number;
+
+    constructor(message: string, errorBody?: TwinErrorBody, retryAfterSeconds?: number) {
+        super(message);
+        this.name = 'TwinTemporarilyUnavailableError';
+        this.errorBody = errorBody;
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+
+// ---------- Asset-domain permissions ----------
+
+/**
+ * The 409 envelope of the customer-wide asset permission surface. The same shape as
+ * {@link TwinPermissionsConflictErrorBody}, but `currentState` is a domain entry rather than a
+ * twin's: the two carry different identity fields (`id` versus `principalId`) and different
+ * capability vocabularies, so a caller that acts on the state it was handed has to know which it
+ * has.
+ *
+ * `ScopesNotProvisioned` never appears here — the asset management scope is seeded once per
+ * customer rather than provisioned per resource.
+ */
+export interface AssetPermissionsConflictErrorBody extends TwinErrorBody {
+    cause: TwinPermissionsConflictCause;
+    currentState?: AssetPrincipalPermissionsGet;
+}
+
+/**
+ * Thrown by the asset permission mutation methods on a 409, which on this surface is always an
+ * etag failure:
+ * - `EtagMismatch` — the etag is stale; re-read (or use {@link currentState}) and retry. Expect
+ *   this routinely: the scope's etag is customer-wide, so any administrator's write invalidates it.
+ * - `EtagRequired` — the write omitted an etag but the principal already held capabilities, so it
+ *   would have replaced state the caller never read.
+ */
+export class AssetPermissionsConflictError extends Error {
+    /**
+     * Which of the two conflicts this is. Named `conflictCause` rather than `cause` so the standard
+     * `Error.cause` — whose consumers expect a wrapped error, not a string — is left alone.
+     */
+    public readonly conflictCause: TwinPermissionsConflictCause;
+    /** The entry as the server holds it, including the etag to retry with. */
+    public readonly currentState?: AssetPrincipalPermissionsGet;
+    public readonly errorBody: AssetPermissionsConflictErrorBody;
+
+    constructor(message: string, errorBody: AssetPermissionsConflictErrorBody) {
+        super(message);
+        this.name = 'AssetPermissionsConflictError';
+        this.conflictCause = errorBody.cause;
+        this.currentState = errorBody.currentState;
+        this.errorBody = errorBody;
+    }
+}

package/src/types/generated.ts

@@ -153,10 +153,6 @@ export interface TwinSpecification {
      * Spaces that are not part of any facility
      */
     aggregatedSpaces?: string[];
-    /**
-     * Ids of Twins that are part of this Twin
-     */
-    aggregatedTwins?: string[];
     elementQuantities?: ElementQuantities[];
     /**
      * Collection of entities that are part of the twin
@@ -170,17 +166,15 @@ export interface TwinSpecification {
      * Unique identifier for the twin
      */
     id?: string;
+    propertySets?: PropertySet[];
     /**
-     * Twin location in WGS84
-     */
-    location?: Location;
-    /**
-     * Name of the Twin
+     * Id of the entity that is the root (top) node of the Twin's entity tree. Must reference a
+     * site or facility present in the EntityCollection.
      */
-    name: string;
-    propertySets?: PropertySet[];
+    rootEntity: string;
     /**
-     * The site of the Twin
+     * Legacy. The site of the Twin. Deprecated: use rootEntity, which is authoritative for the
+     * root of the Twin's entity tree.
      */
     site?: string;
 }
@@ -228,6 +222,11 @@ export interface EntityCollection {
      * Facility part entities in the Twin
      */
     facilityParts?: { [key: string]: FacilityPart };
+    /**
+     * Representation relations declaring that a twin entity is represented by an entity in a
+     * model file, keyed by relation id
+     */
+    representations?: { [key: string]: EntityRepresentation };
     /**
      * Site entities in the Twin
      */
@@ -236,6 +235,10 @@ export interface EntityCollection {
      * Space entities in the Twin
      */
     spaces?: { [key: string]: Space };
+    /**
+     * Twin reference entities in the Twin
+     */
+    twinReferences?: { [key: string]: TwinReference };
     [property: string]: any;
 }
 
@@ -259,11 +262,18 @@ export interface Facility {
      * Type of facility (e.g. IfcBuilding)
      */
     class: FacilityClass;
+    description?: string;
     elementQuantities?: ElementQuantities[];
     /**
      * Unique identifier for the building
      */
     id: string;
+    /**
+     * Location of the facility in WGS84. When the facility is the twin's root entity, this is
+     * the twin's location.
+     */
+    location?: Location;
+    longName?: string;
     name?: string;
     propertySets?: PropertySet[];
 }
@@ -275,6 +285,31 @@ export interface Facility {
  */
 export type FacilityClass = 'IfcBridge' | 'IfcBuilding' | 'IfcMarineFacility' | 'IfcRailway' | 'IfcRoad';
 
+/**
+ * Location of the facility in WGS84. When the facility is the twin's root entity, this is
+ * the twin's location.
+ *
+ * A location in WGS84
+ *
+ * Location of the site in WGS84. When the site is the twin's root entity, this is the
+ * twin's location.
+ */
+export interface Location {
+    /**
+     * Metres above sea level
+     */
+    elevation?: number;
+    epsg: EpsgType;
+    latitude: number;
+    longitude: number;
+    /**
+     * Vector pointing to the true north
+     */
+    trueNorth?: number[];
+}
+
+export type EpsgType = '4326';
+
 export interface PropertySet {
     name: string;
     /**
@@ -431,11 +466,13 @@ export interface FacilityPart {
      * Type of facility part (e.g. IfcBuildingStorey)
      */
     class: FacilityPartClass;
+    description?: string;
     elementQuantities?: ElementQuantities[];
     /**
      * Unique identifier for the facility part
      */
     id: string;
+    longName?: string;
     name?: string;
     propertySets?: PropertySet[];
 }
@@ -452,6 +489,26 @@ export type FacilityPartClass =
     | 'IfcRailwayPart'
     | 'IfcRoadPart';
 
+/**
+ * An objectified relation declaring that a twin entity is represented by another entity.
+ * Modelled as a relation (not an inline attribute) so it stays addressable and extensible,
+ * mirroring how twinReferences objectifies twin-to-twin relations.
+ */
+export interface EntityRepresentation {
+    /**
+     * Reference to the entity that is represented, e.g. twin~twin:{twinId}.entity:{entityId}
+     * for an entity in a twin. Must name an entity: the shared grammar also admits a bare
+     * domain (a scope, not an entity), which the service refuses here
+     */
+    relatingEntity: string;
+    /**
+     * Reference to the entity that provides this entity's representation, e.g.
+     * twin~twin:{twinId}.file:{fileId}/entities/{ifcGid} for an IFC product within one of the
+     * twin's model files. Must name an entity, as relatingEntity must
+     */
+    representedBy: string;
+}
+
 /**
  * A site is a defined area of land, possibly covered with water, upon which constructions
  * are located
@@ -469,15 +526,26 @@ export interface Site {
      * Spaces that are not part of any facility
      */
     aggregatedSpaces?: string[];
+    /**
+     * Twin references nested directly under this site
+     */
+    aggregatedTwinReferences?: string[];
     /**
      * Type of site (i.e. IfcSite)
      */
     class?: SiteType;
+    description?: string;
     elementQuantities?: ElementQuantities[];
     /**
      * Unique identifier for the site
      */
     id?: string;
+    /**
+     * Location of the site in WGS84. When the site is the twin's root entity, this is the
+     * twin's location.
+     */
+    location?: Location;
+    longName?: string;
     /**
      * Name of the site
      */
@@ -507,12 +575,15 @@ export interface Space {
      * Type of space (e.g. IfcSpace)
      */
     class: SpaceType;
+    description?: string;
     elementQuantities?: ElementQuantities[];
     /**
      * Unique identifier for the space
      */
     id: string;
+    longName?: string;
     name?: string;
+    objectType?: string;
     propertySets?: PropertySet[];
 }
 
@@ -521,6 +592,16 @@ export interface Space {
  */
 export type SpaceType = 'IfcSpace';
 
+/**
+ * A reference to another Twin nested within this Twin's spatial hierarchy
+ */
+export interface TwinReference {
+    /**
+     * Id of the referenced (nested) Twin
+     */
+    twin: string;
+}
+
 export interface FilePatchSet {
     /**
      * Ordered list of patch operations to apply
@@ -551,24 +632,3 @@ export interface FilePatch {
  * The patch operation type
  */
 export type Op = 'replace' | 'remove';
-
-/**
- * Twin location in WGS84
- *
- * A location in WGS84
- */
-export interface Location {
-    /**
-     * Metres above sea level
-     */
-    elevation?: number;
-    epsg: EpsgType;
-    latitude: number;
-    longitude: number;
-    /**
-     * Vector pointing to the true north
-     */
-    trueNorth?: number[];
-}
-
-export type EpsgType = '4326';

package/src/types/twin-api.ts

@@ -1,4 +1,5 @@
-import type { PropertySet, ElementQuantities, TwinSpecification, Diagnostics } from './generated';
+import type { PropertySet, ElementQuantities, TwinSpecification, Diagnostics, EpsgType, Location } from './generated';
+import type { TwinBoundCapabilityName } from './twin-permissions-api';
 
 export interface TwinFileReference {
     fileId: string;
@@ -6,6 +7,14 @@ export interface TwinFileReference {
     twinNodeId?: string;
 }
 
+/** WGS84 coordinates of a twin, as returned on the list endpoint (coordinates only — the full
+ *  Location, including elevation and trueNorth, is available on the single-twin GET). */
+export interface Coordinates {
+    epsg: EpsgType;
+    latitude: number;
+    longitude: number;
+}
+
 export interface ListTwinItem {
     id: string;
     name: string;
@@ -20,8 +29,32 @@ export interface ListTwinItem {
     createdUtc: string;
     modifiedBy: string;
     modifiedUtc: string;
+    /** Ids of the Twins nested within this Twin, derived by the service from its twin references. */
+    aggregatedTwins: string[];
+    /** Deduplicated, sorted set of IFC entity classes the twin contains (e.g. IfcBuilding, IfcSpace),
+     *  computed by the service from the specification's entity collection. */
+    classes: string[];
+    /** Id of the Twin that references this Twin (its parent), or omitted for a root Twin. */
+    parentTwin?: string;
+    /** WGS84 coordinates, present only when the twin's specification declares a location. */
+    location?: Coordinates;
+    /**
+     * What the *calling principal* may do with this twin — the whole affordance decision for the
+     * row, so a list of a thousand twins needs no probe per row. Never the twin's access-control
+     * list: that is `listTwinPermissions(twinId)`, which is administration-gated.
+     *
+     * Mixes both capability vocabularies, as the twin-scoped probe does. Where each capability was
+     * granted is answered by `listTwinPermissions(twinId)`, whose rows split `permissions` from
+     * `inheritedPermissions`. Absent on `listTwinVersions`, which does not resolve it.
+     */
+    effectivePermissions?: TwinBoundCapabilityName[];
 }
 
+/**
+ * A twin as returned by the service — by `getTwin` and `getTwinVersion`, and by the write methods
+ * (`createOrUpdateTwin`, `deleteTwin`, `restoreTwin`), which answer with the same shape. Writing a
+ * twin and re-rendering it therefore needs no second fetch.
+ */
 export interface TwinGet extends TwinSpecification {
     id: string;
     etag: string;
@@ -34,6 +67,27 @@ export interface TwinGet extends TwinSpecification {
     modifiedUtc: string;
     fileReferences: TwinFileReference[];
     computedPropertySets?: PropertySet[];
+    /** Ids of the Twins nested within this Twin, derived by the service from its twin references. */
+    aggregatedTwins: string[];
+    /** Id of the Twin that references this Twin (its parent), or omitted for a root Twin. */
+    parentTwin?: string;
+    /** Name of the Twin, derived by the service from the root entity. Read-only; not part of the
+     *  stored specification. */
+    name: string;
+    /** Full WGS84 location of the Twin (including elevation and trueNorth), derived by the service
+     *  from the root entity. Read-only; not part of the stored specification. */
+    location?: Location;
+    /**
+     * Everything the *calling principal* may do with this twin: the capabilities its own scopes
+     * confer, unioned with the twin-bound asset ones held customer-wide. Calculated by the service on
+     * every read, never stored, and never accepted in a `TwinPut` body.
+     *
+     * The verdict, without its provenance — a fetched twin says no more than a listing row does.
+     * Which capabilities are granted here and which come from elsewhere is answered by
+     * `listTwinPermissions(twinId)`, where they are administered. Never the twin's access-control
+     * list either: this describes the caller, not every principal.
+     */
+    effectivePermissions: TwinBoundCapabilityName[];
 }
 
 export interface TwinPut extends TwinSpecification {