@twinfinity/twin 6.0.1 → 6.0.2

package/src/errors.ts

@@ -1,117 +1,379 @@
-import type { TwinGet, AssetGet, TwinFileGet, AssetBatchResponse } from './types';
-
-export interface TwinErrorBody {
-    detail: string;
-    cause: string;
-    item?: {
-        kind: string;
-        id: string;
-        version?: number;
-        field?: string;
-    };
-}
-
-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 {
-    constructor(message: string) {
-        super(message);
-        this.name = 'TwinNotFoundError';
-    }
-}
-
-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 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';
-    }
-}
+import type { TwinGet, AssetGet, TwinFileGet, AssetBatchResponse, AssetCategoryGet, AssetTypeGet } 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'
+    | 'StringIdInUse'
+    | 'CatalogTooLarge'
+    | 'EtagRequired'
+    // 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'
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    | (string & {});
+
+export interface TwinErrorBody {
+    detail: string;
+    cause: TwinErrorCause;
+    item?: {
+        kind: TwinErrorItemKind;
+        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> {
+    try {
+        const parsed = (await response.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 {
+    constructor(message: string) {
+        super(message);
+        this.name = 'TwinNotFoundError';
+    }
+}
+
+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';
+    }
+}

package/src/index.ts

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

package/src/types/Twin.ts

@@ -1,7 +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>;
-}
+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

@@ -1,7 +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>;
-}
+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

@@ -1,60 +1,60 @@
-export interface AssetListItem {
-    id: string;
-    name: string;
-    category?: string;
-    type?: string;
-    twinReference?: string;
-    parentIfcGid?: string;
-    ifcGid?: string;
-    etag: string;
-    createdAt: string;
-    isDeleted?: boolean;
-}
-
-export interface AssetPosition {
-    x?: number;
-    y?: number;
-    z?: number;
-}
-
-export interface AssetGet {
-    id: string;
-    name: 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;
-    category?: string;
-    type?: string;
-    ifcGid?: string;
-    position?: AssetPosition;
-    parentIfcGid?: string;
-    metadata?: Record<string, unknown>;
-    twinReference?: string;
-}
-
-export interface AssetPut {
-    etag: string;
-    name: string;
-    category?: string;
-    type?: string;
-    ifcGid?: string;
-    position?: AssetPosition;
-    parentIfcGid?: string;
-    metadata?: Record<string, unknown>;
-    twinReference?: string;
-}
+export interface AssetListItem {
+    id: string;
+    name: string;
+    category?: string;
+    type?: string;
+    twinReference?: string;
+    parentIfcGid?: string;
+    ifcGid?: string;
+    etag: string;
+    createdAt: string;
+    isDeleted?: boolean;
+}
+
+export interface AssetPosition {
+    x?: number;
+    y?: number;
+    z?: number;
+}
+
+export interface AssetGet {
+    id: string;
+    name: 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;
+    category?: string;
+    type?: string;
+    ifcGid?: string;
+    position?: AssetPosition;
+    parentIfcGid?: string;
+    metadata?: Record<string, unknown>;
+    twinReference?: string;
+}
+
+export interface AssetPut {
+    etag: string;
+    name: string;
+    category?: string;
+    type?: string;
+    ifcGid?: string;
+    position?: AssetPosition;
+    parentIfcGid?: string;
+    metadata?: Record<string, unknown>;
+    twinReference?: string;
+}