@twinfinity/twin 0.0.0-feature.31596

package/src/types/twin-api.ts

@@ -0,0 +1,153 @@
+import type { PropertySet, ElementQuantities, TwinSpecification, Diagnostics, EpsgType, Location } from './generated';
+import type { TwinBoundCapabilityName } from './twin-permissions-api';
+
+export interface TwinFileReference {
+    fileId: string;
+    fileVersion: number;
+    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;
+    etag: string;
+    propertySets?: PropertySet[];
+    computedPropertySets?: PropertySet[];
+    elementQuantities?: ElementQuantities[];
+    relatedContainerIds: string[];
+    version: number;
+    isDeleted?: boolean;
+    createdBy: string;
+    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;
+    relatedContainerIds: string[];
+    version: number;
+    isDeleted?: boolean;
+    createdBy: string;
+    createdUtc: string;
+    modifiedBy: string;
+    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 {
+    etag?: string;
+    relatedContainerIds: string[];
+    fileReferences?: TwinFileReference[];
+}
+
+export interface TwinDelete {
+    etag: string;
+}
+
+export interface TwinVersionContentResponse {
+    twinId: string;
+    twinVersion: number;
+    status: string;
+    processors: TwinProcessorResponse[];
+    content: TwinContentResponse[];
+    computedPropertySets: TwinComputedPropertySetsResponse[];
+}
+
+export interface TwinProcessorResponse {
+    processorId: string;
+    processorName: string;
+    processorDescription?: string;
+    status: string;
+}
+
+export interface TwinContentResponse {
+    id: string;
+    processorId: string;
+    format: string;
+    description?: string;
+    receivedAt: string;
+}
+
+export interface TwinComputedPropertySetsResponse {
+    processorId: string;
+    propertySets: PropertySet[];
+    receivedAt: string;
+}
+
+export interface TwinProcessorEvent {
+    id: string;
+    processorId: string;
+    eventType: string;
+    eventTimestampUtc: string;
+    details?: unknown;
+    message?: string;
+}
+
+export interface DiagnosticsSummary {
+    fatalCount: number;
+    errorCount: number;
+    warningCount: number;
+}
+
+export interface TwinDiagnosticsResponse {
+    twinId: string;
+    twinVersion: number;
+    summary: DiagnosticsSummary;
+    diagnostics: Diagnostics;
+}

package/src/types/twin-file-api.ts

@@ -0,0 +1,67 @@
+export interface TwinFileTransform {
+    qx?: number;
+    qy?: number;
+    qz?: number;
+    qw?: number;
+    sx?: number;
+    sy?: number;
+    sz?: number;
+    x?: number;
+    y?: number;
+    z?: number;
+}
+
+export interface TwinFileGet {
+    id: string;
+    twinId: string;
+    version: number;
+    source: TwinFileSource;
+    name: string;
+    comment?: string;
+    quality: number;
+    etag: string;
+    isDeleted: boolean;
+    createdBy: string;
+    createdUtc: string;
+    modifiedBy: string;
+    modifiedUtc: string;
+    transform?: TwinFileTransform;
+}
+
+export interface TwinFileSource {
+    changeId: string;
+    changeVersion: number;
+    sourceType: string;
+}
+
+export interface TwinFilePut {
+    source: TwinFileSource;
+    name: string;
+    comment?: string;
+    quality: number | null;
+    etag?: string;
+    isDeleted?: boolean;
+    transform?: TwinFileTransform;
+}
+
+export interface TwinFileDelete {
+    etag: string;
+}
+
+export interface TwinFileRestore {
+    etag: string;
+}
+
+export interface TwinFileListOptions {
+    includeDeleted?: boolean;
+    checkedIn?: boolean;
+    version?: number;
+    page?: string;
+    limit?: number;
+}
+
+export interface TwinFileVersionListOptions {
+    includeDeleted?: boolean;
+    offset?: number;
+    limit?: number;
+}

package/src/types/twin-permissions-api.ts

@@ -0,0 +1,257 @@
+/**
+ * Named, customer-scoped capability the caller can exercise against the Twin service, granted on
+ * the asset domain — the one thing the service governs that is not bound to a single
+ * twin. Returned by `GET /twins/permissions/me`, listed by `GET /twins/permissions` and accepted by
+ * `PUT /twins/permissions/{principalId}`. Mirrors `Twinfinity.Twin.Model.TwinCapability`.
+ *
+ * Distinct from {@link TwinScopedCapability}, which is held on one twin. The two vocabularies never
+ * share a name, because `GET /twins/{twinId}/permissions/me` answers with one flat array mixing
+ * both and each name is resolved against the vocabulary it came from.
+ *
+ * This is the *write* vocabulary — the capabilities a grant may ask for. Values read back from the
+ * service are {@link TwinCapabilityName}, which also admits capabilities a newer server knows and
+ * this client does not; such a value is "not granted" as far as this client is concerned, and must
+ * be ignored rather than treated as an error.
+ */
+export type TwinCapability = 'ViewAssets' | 'EditAssets' | 'DeleteAssets' | 'EditAssetTypes' | 'ManageAssetPermissions';
+
+/**
+ * A capability as *read back* from the service: one of {@link TwinCapability}, or a name a newer
+ * server knows and this client does not.
+ *
+ * Deliberately wider than the write vocabulary. A grant may only ask for capabilities that exist,
+ * so {@link TwinCapability} stays closed and a typo is a compile error; a listing, though, is
+ * whatever the server says, and ADR-0008 §5 makes tolerating unknown names a rule for readers. The
+ * `(string & {})` tail keeps autocomplete on the five known values while forcing consumers who
+ * `switch` over a capability to write a default arm — which is where an unknown one must land.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type TwinCapabilityName = TwinCapability | (string & {});
+
+/**
+ * Response body for `GET /twins/permissions/me`. The `permissions` array
+ * lists only capabilities the caller actually holds; absence means "not
+ * granted." Use `permissions.includes('EditAssetTypes')` etc. for gating.
+ *
+ * Wrapped under a key (rather than a bare array) so future fields — an
+ * etag, an identity echo, expiry — can be added without a shape break.
+ */
+export interface MyPermissions {
+    permissions: TwinCapabilityName[];
+}
+
+/**
+ * Named capability a principal can hold on one specific twin, granted through
+ * `/twins/{twinId}/permissions`. Mirrors `Twinfinity.Twin.Model.TwinScopedCapability`.
+ *
+ * Distinct from {@link TwinCapability}, which is customer-scoped and speaks about the
+ * asset domain rather than about one twin.
+ *
+ * This is the *write* vocabulary — the four capabilities a grant may ask for. Values read back
+ * from the service are {@link TwinScopedCapabilityName}, which also admits capabilities a newer
+ * server knows and this client does not; such a value is "not granted" as far as this client is
+ * concerned, and must be ignored rather than treated as an error.
+ */
+export type TwinScopedCapability = 'ReadTwin' | 'WriteTwin' | 'DeleteTwin' | 'ManageTwinPermissions';
+
+/**
+ * A capability as *read back* from the service: one of {@link TwinScopedCapability}, or a name a
+ * newer server knows and this client does not.
+ *
+ * Deliberately wider than the write vocabulary. A grant may only ask for capabilities that exist,
+ * so {@link TwinPermissionsPut} stays closed and a typo is a compile error; a listing, though, is
+ * whatever the server says, and ADR-0008 §5 makes tolerating unknown names a rule for readers. The
+ * `(string & {})` tail keeps autocomplete on the four known values while forcing consumers who
+ * `switch` over a capability to write a default arm — which is where an unknown one must land.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type TwinScopedCapabilityName = TwinScopedCapability | (string & {});
+
+/**
+ * A capability as read back from `GET /twins/{twinId}/permissions/me`. That probe answers with one
+ * flat array mixing both vocabularies: the twin's own {@link TwinScopedCapability} values, plus the
+ * asset-instance capabilities `ViewAssets`, `EditAssets` and `DeleteAssets` from the customer-wide
+ * asset domain, which gate the assets hanging off the twin. `EditAssetTypes` and
+ * `ManageAssetPermissions` are not twin-bound and are absent — ask `GET /twins/permissions/me`.
+ *
+ * Names never collide across the two enums, so `includes('EditAssets')` is unambiguous. As with
+ * {@link TwinScopedCapabilityName}, the `(string & {})` tail admits names a newer server knows.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type TwinBoundCapabilityName = TwinScopedCapability | TwinCapability | (string & {});
+
+/**
+ * Response body for `GET /twins/{twinId}/permissions/me`: the capabilities the caller
+ * holds on that twin. The endpoint is open to every authenticated caller — an empty
+ * list is an honest answer, not a refusal — so it is safe to call before rendering.
+ */
+export interface MyTwinPermissions {
+    permissions: TwinBoundCapabilityName[];
+}
+
+/**
+ * One entry of an access-control-list row's `inheritedPermissions`: capabilities the row's principal
+ * holds from a grant made somewhere other than this resource, and where that grant lives.
+ *
+ * `source` is an entity reference. A grant held customer-wide is spelled as the bare domain token
+ * with no trailing separator — `"twin"` for the asset capabilities a twin reports — which is where
+ * an administration UI has to go to change them.
+ */
+export interface InheritedPermissions {
+    source: string;
+    permissions: TwinBoundCapabilityName[];
+}
+
+/**
+ * One principal's permission entry on a twin, as listed by
+ * `GET /twins/{twinId}/permissions` and returned by the mutation endpoints.
+ *
+ * This is where the provenance split lives: {@link permissions} is what an administrator can edit
+ * here, {@link inheritedPermissions} is what confers ability on the twin from elsewhere, and
+ * {@link effectivePermissions} is what this principal can actually do. All three describe *this
+ * row's principal* — a twin's own representation is the one that describes the caller, and it
+ * carries the verdict alone.
+ */
+export interface TwinPrincipalPermissionsGet {
+    /** Global id of the principal (a group; users are not grantable per ADR-0008 §6). */
+    principalId: string;
+    /** The principal's display title. */
+    name: string;
+    /**
+     * What this principal holds from grants made on the twin *itself*, and the only part this
+     * surface writes: `setTwinPermissions` replaces exactly this set.
+     */
+    permissions: TwinScopedCapabilityName[];
+    /**
+     * One entry per place outside this twin that confers ability on it. A twin has one possible
+     * source: the domain, `source: 'twin'`, carrying whichever of `ViewAssets`, `EditAssets` and
+     * `DeleteAssets` this principal holds customer-wide, because `twins/{twinId}/assets` gates on
+     * them. The asset catalog capability and `ManageAssetPermissions` never appear — they are
+     * domain-wide and confer nothing on one twin. Empty when the principal holds none of them.
+     */
+    inheritedPermissions: InheritedPermissions[];
+    /**
+     * The union of {@link permissions} and every {@link inheritedPermissions} entry — what this
+     * principal can actually do on the twin. Calculated by the service on every read and never
+     * accepted on a write. Mixes both capability vocabularies, so it is typed the widened way.
+     */
+    effectivePermissions: TwinBoundCapabilityName[];
+    /**
+     * True exactly when a `PUT` or `DELETE` naming this principal would be refused with
+     * `SystemPrincipalImmutable`: the twin's own default groups and the seeded Twinfinity
+     * system principals. Render the control as disabled rather than discovering the
+     * constraint by attempting a write.
+     */
+    readOnly: boolean;
+    /**
+     * Optimistic concurrency token for this entry, to send back on the next mutation of this
+     * principal. Two entries in one listing may carry different values — edit each with the one its
+     * own row reported. Absent when the service had none to report.
+     */
+    etag?: string;
+}
+
+/** Request body for `PUT /twins/{twinId}/permissions/{principalId}`. */
+export interface TwinPermissionsPut {
+    /**
+     * The capability set replacing whatever this principal held of the four above; bits
+     * outside this vocabulary survive untouched. An empty list revokes all four, which
+     * leaves the principal with no listing entry at all unless it carries such bits.
+     */
+    permissions: TwinScopedCapability[];
+    /**
+     * This principal's etag, from its entry in a prior listing or mutation response. May be omitted only to create
+     * the grants of a principal that holds nothing on the twin yet — the one case with no
+     * entry to read one from. Omitting it on what turns out to be a replacement is refused
+     * with `EtagRequired`, and a stale value with `EtagMismatch`.
+     */
+    etag?: string;
+}
+
+/**
+ * One of the default groups a twin owns — `TwinReaders`, `TwinContributors`,
+ * `TwinAdministrators` — provisioned for it when it is created.
+ *
+ * Address a group by {@link id}: {@link name} is informational and not unique across
+ * twins, since every twin's groups carry the same three names. The groups' own grants
+ * are immutable; confer a preset by changing a group's membership through the
+ * Permission service instead.
+ */
+export interface TwinGroupGet {
+    name: string;
+    id: string;
+    title: string;
+}
+
+/** Response body for `GET /twins/{twinId}/groups`. */
+export interface TwinGroupsGet {
+    groups: TwinGroupGet[];
+}
+
+/**
+ * One principal's permission entry on the asset domain, as listed by `GET /twins/permissions` and
+ * returned by the mutation endpoints.
+ *
+ * The etag is customer-wide rather than per principal, so every entry in a listing carries the same
+ * value and a write by any administrator invalidates the one every other administrator is holding.
+ */
+export interface AssetPrincipalPermissionsGet {
+    /** Global id of the principal (a group; users are not grantable). */
+    id: string;
+    /** The principal's display name. */
+    name: string;
+    /** The capabilities this principal holds on the domain. Empty after a full revoke. */
+    permissions: TwinCapabilityName[];
+    /**
+     * True exactly when a `PUT` or `DELETE` naming this principal would be refused with
+     * `SystemPrincipalImmutable`: the seeded default groups. Render the control as disabled rather
+     * than discovering the constraint by attempting a write. False for everything else, the
+     * all-authenticated principal included, whose capabilities are mutable.
+     */
+    readOnly: boolean;
+    /**
+     * Optimistic concurrency token, to send back on the next mutation. It is customer-wide rather
+     * than per principal, so any administrator's write invalidates the value every other one holds.
+     *
+     * Because it belongs to the domain rather than to the principal, a revocation answers with one
+     * too, even though the revoked principal no longer has a listing entry — so a caller may chain
+     * another write straight after a `deleteAssetPermissions` without re-reading the listing.
+     *
+     * Absent only before the domain has been provisioned for the customer.
+     */
+    etag?: string;
+}
+
+/** Request body for `PUT /twins/permissions/{principalId}`. */
+export interface AssetPermissionsPut {
+    /**
+     * The capability set replacing whatever this principal held; an empty list revokes everything
+     * and leaves the principal with no listing entry at all.
+     */
+    permissions: TwinCapability[];
+    /**
+     * The domain's etag. May be omitted only to create the grants of a principal that holds nothing
+     * yet — the one case with no entry to read one from. Omitting it on what turns out to be a
+     * replacement is refused with `EtagRequired`, and a stale value with `EtagMismatch`.
+     */
+    etag?: string;
+}
+
+/**
+ * One of the asset domain's default groups — `AssetsReaders`, `AssetsContributors`,
+ * `AssetsAdministrators` — seeded once per customer.
+ *
+ * Unlike a twin's groups, {@link name} is unique across the customer and is what
+ * {@link ITwinClient.getAssetGroup} addresses. The groups' own grants are immutable; confer a
+ * preset by changing a group's membership through the permission API instead.
+ */
+export interface AssetGroupGet {
+    name: string;
+    id: string;
+    title: string;
+}
+
+/** Response body for `GET /twins/groups`. */
+export interface AssetGroupsGet {
+    groups: AssetGroupGet[];
+}