@twinfinity/twin 0.0.0-feature.31596

package/src/errors.ts

@@ -0,0 +1,567 @@
+import type {
+    TwinGet,
+    AssetGet,
+    TwinFileGet,
+    AssetBatchResponse,
+    AssetCategoryGet,
+    AssetTypeGet,
+    TwinPrincipalPermissionsGet,
+    AssetPrincipalPermissionsGet
+} from './types';
+import type { AttachmentGet } from './types/asset-attachment-api';
+
+/**
+ * Closed union of `cause` values the Twin service emits on a 400 response. Mirrors
+ * `TwinBadRequestCause` in `backend/services/Twinfinity.Twin/Controllers/Model/TwinStatus.cs`.
+ * The trailing `(string & {})` keeps autocomplete on the known values while still
+ * accepting unknown causes at the type level — a forward-compat pattern: a new
+ * cause emitted by a newer server doesn't break older clients that pattern-match
+ * on the union. Matches the shape of `TwinCapability` in
+ * `types/twin-permissions-api.ts`.
+ */
+export type TwinErrorCause =
+    | 'NotAllowedToEditDeletedItem'
+    | 'NotAllowedToDeleteItem'
+    | 'ImmutableField'
+    | 'ReferencedItemNotFound'
+    | 'ReferencedItemDeleted'
+    | 'FileNotOwnedByTwin'
+    | 'DuplicateFileReference'
+    | 'MultipleVersionsOfSameFileOnSameNode'
+    | 'LimitOutOfRange'
+    | 'OffsetOutOfRange'
+    | 'IdMismatchBetweenUrlAndBody'
+    | 'BatchSizeEmpty'
+    | 'BatchSizeExceedsMaximum'
+    | 'InvalidParameterCombination'
+    | 'DocumentChangeNotFound'
+    | 'DeletePermissionRequired'
+    | 'CannotEditDeletedFile'
+    | 'CannotMoveFileBetweenTwins'
+    | 'ContainerDoesNotExist'
+    | 'DuplicateContainerIds'
+    | 'InsufficientPermissionsOnContainer'
+    | 'DuplicateId'
+    | 'MetadataTooLarge'
+    | 'InvalidTransform'
+    | 'InvalidFilePatches'
+    | 'MetadataValidationFailed'
+    | 'MetadataSchemaInvalid'
+    | 'AssetTypeNotFound'
+    | 'AssetCategoryAndTypeRequired'
+    | 'AssetDescriptionTooLong'
+    | '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
+    | (string & {});
+
+/**
+ * Closed union of `item.kind` values the server emits. Mirrors `ItemKind` in
+ * `backend/services/Twinfinity.Twin/Model/ItemReference.cs`. Same forward-compat
+ * shape as {@link TwinErrorCause}.
+ */
+export type TwinErrorItemKind =
+    | 'Twin'
+    | 'Asset'
+    | 'File'
+    | 'DocumentChange'
+    | 'AssetCategory'
+    | 'AssetType'
+    | 'Attachment'
+    | 'Document'
+    | 'Principal'
+    | 'Request'
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    | (string & {});
+
+export interface TwinErrorBody {
+    detail: string;
+    cause: TwinErrorCause;
+    item?: {
+        kind: TwinErrorItemKind;
+        // 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;
+    };
+}
+
+/**
+ * Parse a non-OK response body as a {@link TwinErrorBody}. Falls back to a
+ * synthetic body carrying the response text (or statusText) when the body
+ * isn't valid JSON — for example when a WAF or intermediate proxy injects
+ * an HTML 4xx page. Callers can therefore always pattern-match on
+ * `errorBody.cause` without an outer try/catch around a bare
+ * `response.json()`.
+ *
+ * The synthetic body uses `cause: 'Unknown'`, which is permitted by the
+ * `(string & {})` forward-compat tail on {@link TwinErrorCause}. Consumers
+ * 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 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.
+        if (parsed && typeof parsed.detail === 'string') return parsed;
+        return { detail: JSON.stringify(parsed), cause: 'Unknown' };
+    } catch {
+        const text = await response.text().catch(() => '');
+        return { detail: text || response.statusText || `HTTP ${response.status}`, cause: 'Unknown' };
+    }
+}
+
+export class TwinValidationError extends Error {
+    public readonly errorBody?: TwinErrorBody;
+
+    constructor(message: string, errorBody?: TwinErrorBody) {
+        super(message);
+        this.name = 'TwinValidationError';
+        this.errorBody = errorBody;
+    }
+}
+
+export class TwinConflictError extends Error {
+    public readonly currentTwin: TwinGet;
+
+    constructor(message: string, currentTwin: TwinGet) {
+        super(message);
+        this.name = 'TwinConflictError';
+        this.currentTwin = currentTwin;
+    }
+}
+
+export class TwinNotFoundError extends Error {
+    /** 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;
+    }
+}
+
+export class ProcessorNotFoundError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'ProcessorNotFoundError';
+    }
+}
+
+export class AssetValidationError extends Error {
+    public readonly errorBody?: TwinErrorBody;
+
+    constructor(message: string, errorBody?: TwinErrorBody) {
+        super(message);
+        this.name = 'AssetValidationError';
+        this.errorBody = errorBody;
+    }
+}
+
+export class AssetForbiddenError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'AssetForbiddenError';
+    }
+}
+
+export class AssetConflictError extends Error {
+    public readonly currentAsset: AssetGet;
+
+    constructor(message: string, currentAsset: AssetGet) {
+        super(message);
+        this.name = 'AssetConflictError';
+        this.currentAsset = currentAsset;
+    }
+}
+
+export class AssetNotFoundError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'AssetNotFoundError';
+    }
+}
+
+export class AssetAttachmentConflictError extends Error {
+    public readonly currentAttachment: AttachmentGet;
+
+    constructor(message: string, currentAttachment: AttachmentGet) {
+        super(message);
+        this.name = 'AssetAttachmentConflictError';
+        this.currentAttachment = currentAttachment;
+    }
+}
+
+export class AssetAttachmentNotFoundError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'AssetAttachmentNotFoundError';
+    }
+}
+
+export class AssetBatchError extends Error {
+    public readonly response: AssetBatchResponse;
+
+    constructor(message: string, response: AssetBatchResponse) {
+        super(message);
+        this.name = 'AssetBatchError';
+        this.response = response;
+    }
+}
+
+export class TwinFileValidationError extends Error {
+    public readonly errorBody?: TwinErrorBody;
+
+    constructor(message: string, errorBody?: TwinErrorBody) {
+        super(message);
+        this.name = 'TwinFileValidationError';
+        this.errorBody = errorBody;
+    }
+}
+
+export class TwinFileConflictError extends Error {
+    public readonly currentTwinFile: TwinFileGet;
+
+    constructor(message: string, currentTwinFile: TwinFileGet) {
+        super(message);
+        this.name = 'TwinFileConflictError';
+        this.currentTwinFile = currentTwinFile;
+    }
+}
+
+export class TwinFileNotFoundError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'TwinFileNotFoundError';
+    }
+}
+
+// ---------- Asset categories ----------
+
+export class AssetCategoryValidationError extends Error {
+    public readonly errorBody?: TwinErrorBody;
+
+    constructor(message: string, errorBody?: TwinErrorBody) {
+        super(message);
+        this.name = 'AssetCategoryValidationError';
+        this.errorBody = errorBody;
+    }
+}
+
+export class AssetCategoryConflictError extends Error {
+    public readonly currentCategory: AssetCategoryGet;
+
+    constructor(message: string, currentCategory: AssetCategoryGet) {
+        super(message);
+        this.name = 'AssetCategoryConflictError';
+        this.currentCategory = currentCategory;
+    }
+}
+
+export class AssetCategoryNotFoundError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'AssetCategoryNotFoundError';
+    }
+}
+
+export class AssetCategoryForbiddenError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'AssetCategoryForbiddenError';
+    }
+}
+
+// ---------- Asset types ----------
+
+export class AssetTypeValidationError extends Error {
+    public readonly errorBody?: TwinErrorBody;
+
+    constructor(message: string, errorBody?: TwinErrorBody) {
+        super(message);
+        this.name = 'AssetTypeValidationError';
+        this.errorBody = errorBody;
+    }
+}
+
+export class AssetTypeConflictError extends Error {
+    public readonly currentType: AssetTypeGet;
+
+    constructor(message: string, currentType: AssetTypeGet) {
+        super(message);
+        this.name = 'AssetTypeConflictError';
+        this.currentType = currentType;
+    }
+}
+
+export class AssetTypeNotFoundError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'AssetTypeNotFoundError';
+    }
+}
+
+export class AssetTypeForbiddenError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'AssetTypeForbiddenError';
+    }
+}
+
+// ---------- Asset catalog ----------
+
+/**
+ * Wire shape returned by `GET /asset-type-catalog` with a 400 when the
+ * tenant's catalog can't be served as a single round-trip — same shape as
+ * {@link TwinErrorBody} plus structured counts so picker UIs can render a
+ * precise message without parsing `detail`.
+ *
+ * Mirrors `AssetCatalogTooLargeResponse` in
+ * `backend/services/Twinfinity.Twin/Controllers/Model/AssetCatalogDtos.cs`.
+ */
+export interface AssetCatalogTooLargeErrorBody extends TwinErrorBody {
+    cause: 'CatalogTooLarge';
+    categoriesCount: number;
+    typesCount: number;
+    maxCatalogSize: number;
+    categoriesOverflowed: boolean;
+    typesOverflowed: boolean;
+}
+
+/**
+ * Thrown by `getAssetTypeCatalog` when the customer's catalog exceeds the
+ * per-customer cap. The catalog endpoint is a single-round-trip view; tenants
+ * over the cap must switch to a paginated endpoint (not yet shipped). Surfaced
+ * as a hard failure rather than silent truncation so picker UIs can render
+ * "too many rows, use search" instead of "out of types."
+ *
+ * `categoriesOverflowed` / `typesOverflowed` identify which side(s) breached
+ * the cap; both can be true. `categoriesCount` / `typesCount` are the observed
+ * counts (≥ `maxCatalogSize` for the overflowing side(s)).
+ */
+export class AssetCatalogTooLargeError extends Error {
+    public readonly errorBody: AssetCatalogTooLargeErrorBody;
+    public readonly categoriesCount: number;
+    public readonly typesCount: number;
+    public readonly maxCatalogSize: number;
+    public readonly categoriesOverflowed: boolean;
+    public readonly typesOverflowed: boolean;
+
+    constructor(message: string, errorBody: AssetCatalogTooLargeErrorBody) {
+        super(message);
+        this.name = 'AssetCatalogTooLargeError';
+        this.errorBody = errorBody;
+        this.categoriesCount = errorBody.categoriesCount;
+        this.typesCount = errorBody.typesCount;
+        this.maxCatalogSize = errorBody.maxCatalogSize;
+        this.categoriesOverflowed = errorBody.categoriesOverflowed;
+        this.typesOverflowed = errorBody.typesOverflowed;
+    }
+}
+
+/**
+ * Type guard for a {@link TwinErrorBody} that carries `CatalogTooLarge`
+ * with the structured count fields the dedicated wire shape adds on top of
+ * the standard envelope. Used by the client to decide whether to throw a
+ * typed {@link AssetCatalogTooLargeError} or fall through to a generic
+ * validation error when the server sends a malformed payload.
+ */
+export function isAssetCatalogTooLargeErrorBody(body: TwinErrorBody): body is AssetCatalogTooLargeErrorBody {
+    return (
+        body.cause === 'CatalogTooLarge' &&
+        typeof (body as Partial<AssetCatalogTooLargeErrorBody>).categoriesCount === 'number' &&
+        typeof (body as Partial<AssetCatalogTooLargeErrorBody>).typesCount === 'number' &&
+        typeof (body as Partial<AssetCatalogTooLargeErrorBody>).maxCatalogSize === 'number' &&
+        typeof (body as Partial<AssetCatalogTooLargeErrorBody>).categoriesOverflowed === 'boolean' &&
+        typeof (body as Partial<AssetCatalogTooLargeErrorBody>).typesOverflowed === 'boolean'
+    );
+}
+
+// ---------- Authentication ----------
+
+/**
+ * Thrown when the server returns 401 (Unauthorized). Distinct from forbidden
+ * errors: 401 means "no valid auth context" (the caller should redirect to
+ * login / refresh tokens), while 403 means "authenticated but not granted"
+ * (the UI should surface a permissions hint or render disabled affordances).
+ */
+export class TwinUnauthenticatedError extends Error {
+    constructor(message: string) {
+        super(message);
+        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/index.ts

@@ -0,0 +1,3 @@
+export { type ITwinClient, TwinClient } from './TwinClient';
+export * from './types';
+export * from './errors';

package/src/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.common.json",
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "noEmit": false,
+    "outDir": "../dist"
+  },
+  "include": ["**/*.ts"],
+  "references": [
+    { "path": "../../twinfinity-authentication/src" },
+    { "path": "../../twinfinity-t8-client-model/src" }
+  ]
+}

package/src/types/Twin.ts

@@ -0,0 +1,7 @@
+import { T8ClientModel } from '@twinfinity/t8-client-model';
+
+export class Twin<TProject, TProduct, TEntityType, TUnit> {
+    id: string;
+    version: number;
+    model?: T8ClientModel<TProject, TProduct, TEntityType, TUnit>;
+}

package/src/types/TwinGeometryInfo.ts

@@ -0,0 +1,7 @@
+import type { T8GIModelGeneric } from '@twinfinity/t8-client-model';
+
+export interface TwinGeometryInfo<TMeshDescriptor, TStyle, TRegion> {
+    id: string;
+    version: number;
+    model?: T8GIModelGeneric<TMeshDescriptor, TStyle, TRegion>;
+}

package/src/types/asset-api.ts

@@ -0,0 +1,69 @@
+export interface AssetListItem {
+    id: string;
+    name: string;
+    /** Free-text description, common to all asset categories and types. Not part of `metadata`. */
+    description?: string;
+    category?: string;
+    type?: string;
+    twinReference?: string;
+    parentIfcGid?: string;
+    ifcGid?: string;
+    position?: AssetPosition;
+    etag: string;
+    createdAt: string;
+    isDeleted?: boolean;
+}
+
+export interface AssetPosition {
+    x?: number;
+    y?: number;
+    z?: number;
+}
+
+export interface AssetGet {
+    id: string;
+    name: string;
+    /** Free-text description, common to all asset categories and types. Not part of `metadata`. */
+    description?: string;
+    category?: string;
+    type?: string;
+    ifcGid?: string;
+    twinReference?: string;
+    position?: AssetPosition;
+    parentIfcGid?: string;
+    metadata?: Record<string, unknown>;
+    etag: string;
+    createdUtc: string;
+    createdBy: string;
+    modifiedUtc: string;
+    modifiedBy: string;
+    isDeleted?: boolean;
+}
+
+export interface AssetPost {
+    id?: string;
+    name: string;
+    /** Free-text description, common to all asset categories and types. Not part of `metadata`. */
+    description?: string;
+    category?: string;
+    type?: string;
+    ifcGid?: string;
+    position?: AssetPosition;
+    parentIfcGid?: string;
+    metadata?: Record<string, unknown>;
+    twinReference?: string;
+}
+
+export interface AssetPut {
+    etag: string;
+    name: string;
+    /** Free-text description, common to all asset categories and types. Not part of `metadata`. */
+    description?: string;
+    category?: string;
+    type?: string;
+    ifcGid?: string;
+    position?: AssetPosition;
+    parentIfcGid?: string;
+    metadata?: Record<string, unknown>;
+    twinReference?: string;
+}