@twinfinity/twin 5.0.3-ci.27942

package/src/TwinClient.ts

@@ -0,0 +1,1274 @@
+import { TwinfinityHttpClient, HttpMethod } from '@twinfinity/authentication';
+import {
+    readT8ClientModelWithFactories,
+    readT8GIModelWithFactories,
+    T8ClientEntityTypeDTO,
+    T8ClientModel,
+    T8ClientModelDTO,
+    T8ClientProductConnectionsDTO,
+    T8ClientProductDTO,
+    T8ClientProjectConnectionsDTO,
+    T8ClientProjectDTO,
+    T8ClientUnitDTO,
+    T8EntityType,
+    T8GIMeshDescriptor,
+    T8GIMeshDescriptorDTO,
+    T8GIStyle,
+    T8GIStyleDTO,
+    T8GIRegion,
+    T8GIRegionDTO,
+    T8Product,
+    T8Project,
+    T8Unit
+} from '@twinfinity/t8-client-model';
+import type { T8GIModelGeneric } from '@twinfinity/t8-client-model';
+import type {
+    PaginatedResponse,
+    ListTwinItem,
+    TwinGet,
+    TwinPut,
+    TwinVersionContentResponse,
+    TwinProcessorEvent,
+    TwinDiagnosticsResponse,
+    AssetListItem,
+    AssetGet,
+    AssetPost,
+    AssetPut,
+    AssetBatchOperation,
+    AssetBatchResponse,
+    AssetBatchGetResponse,
+    TwinFileGet,
+    TwinFilePut,
+    TwinFileDelete,
+    TwinFileListOptions,
+    TwinFileVersionListOptions,
+    TwinContentResponse
+} from './types';
+import {
+    TwinValidationError,
+    TwinConflictError,
+    TwinNotFoundError,
+    ProcessorNotFoundError,
+    AssetValidationError,
+    AssetConflictError,
+    AssetNotFoundError,
+    AssetBatchError,
+    TwinFileValidationError,
+    TwinFileConflictError,
+    TwinFileNotFoundError
+} from './errors';
+import { Twin } from './types/Twin';
+import { TwinGeometryInfo } from './types/TwinGeometryInfo';
+
+export interface ITwinClient {
+    listTwins(
+        relatedTo?: string,
+        page?: string,
+        limit?: number,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<ListTwinItem>>;
+
+    listAllTwins(relatedTo?: string, signal?: AbortSignal): Promise<ListTwinItem[]>;
+
+    getTwin(twin: string | { id: string; version: number }, signal?: AbortSignal): Promise<TwinGet>;
+
+    listTwinVersions(
+        id: string,
+        options?: {
+            includeDeleted?: boolean;
+            page?: string;
+            limit?: number;
+        },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<ListTwinItem>>;
+
+    downloadTwinContent(
+        twinId: string,
+        twinVersion: number,
+        content: TwinContentResponse,
+        signal?: AbortSignal
+    ): Promise<ArrayBuffer>;
+
+    loadTwin(
+        twin: string | { id: string; version: number },
+        signal?: AbortSignal
+    ): Promise<Twin<T8Project, T8Product<T8EntityType>, T8EntityType, T8Unit>>;
+
+    loadTwinWithFactories<TProject, TProduct, TEntityType, TUnit>(
+        twin: string | { id: string; version: number },
+        projectFactory: (dto: T8ClientProjectDTO<TUnit>) => TProject,
+        productFactory: (dto: T8ClientProductDTO<TUnit>) => TProduct,
+        entityTypeFactory: (dto: T8ClientEntityTypeDTO<TUnit>) => TEntityType,
+        unitFactory: (dto: T8ClientUnitDTO, dataModel: T8ClientModelDTO) => TUnit,
+        connectProject: (dto: T8ClientProjectConnectionsDTO<TProduct>, project: TProject) => void,
+        connectProduct: (dto: T8ClientProductConnectionsDTO<TProduct, TEntityType>, product: TProduct) => void,
+        signal?: AbortSignal
+    ): Promise<Twin<TProject, TProduct, TEntityType, TUnit>>;
+
+    loadGeometryInfo(
+        twin: string | { id: string; version: number },
+        signal?: AbortSignal
+    ): Promise<TwinGeometryInfo<T8GIMeshDescriptor, T8GIStyle, T8GIRegion>>;
+
+    loadGeometryInfoWithFactories<TMeshDescriptor, TStyle, TRegion>(
+        twin: string | { id: string; version: number },
+        meshDescriptorFactory: (dto: T8GIMeshDescriptorDTO) => TMeshDescriptor,
+        styleFactory: (dto: T8GIStyleDTO) => TStyle,
+        regionFactory: (dto: T8GIRegionDTO) => TRegion,
+        signal?: AbortSignal
+    ): Promise<TwinGeometryInfo<TMeshDescriptor, TStyle, TRegion>>;
+
+    createOrUpdateTwin(twinId: string, twin: TwinPut, signal?: AbortSignal): Promise<TwinGet>;
+    updateTwin(twinId: string, twin: TwinPut, signal?: AbortSignal): Promise<TwinGet>;
+
+    restoreTwin(twinId: string, etag: string, signal?: AbortSignal): Promise<TwinGet>;
+
+    getTwinVersionContent(
+        twinId: string,
+        twinVersion: number,
+        signal?: AbortSignal
+    ): Promise<TwinVersionContentResponse>;
+    getTwinContent(twinId: string, signal?: AbortSignal): Promise<TwinVersionContentResponse>;
+
+    getTwinDiagnostics(twinId: string, signal?: AbortSignal): Promise<TwinDiagnosticsResponse>;
+    getTwinVersionDiagnostics(
+        twinId: string,
+        twinVersion: number,
+        signal?: AbortSignal
+    ): Promise<TwinDiagnosticsResponse>;
+
+    getTwinVersionEvents(
+        twinId: string,
+        twinVersion: number,
+        offset?: number,
+        limit?: number,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<TwinProcessorEvent>>;
+
+    getProcessorEvents(
+        twinId: string,
+        twinVersion: number,
+        processorId: string,
+        offset?: number,
+        limit?: number,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<TwinProcessorEvent>>;
+
+    listAssets(
+        twinId: string,
+        offset?: number,
+        limit?: number,
+        options?: { includeDeleted?: boolean },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<AssetListItem>>;
+
+    getAsset(twinId: string, assetId: string, signal?: AbortSignal): Promise<AssetGet>;
+
+    createAssets(twinId: string, assets: AssetPost[], signal?: AbortSignal): Promise<AssetGet[]>;
+
+    updateAsset(twinId: string, assetId: string, asset: AssetPut, signal?: AbortSignal): Promise<AssetGet>;
+
+    deleteAsset(twinId: string, assetId: string, etag: string, signal?: AbortSignal): Promise<AssetGet>;
+
+    deleteTwin(twinId: string, etag: string, signal?: AbortSignal): Promise<TwinGet>;
+
+    listTwinFiles(
+        twinId: string,
+        options?: TwinFileListOptions,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<TwinFileGet>>;
+    getTwinFile(twinId: string, fileId: string, signal?: AbortSignal): Promise<TwinFileGet>;
+
+    createOrUpdateTwinFile(
+        twinId: string,
+        fileId: string,
+        twinFile: TwinFilePut,
+        signal?: AbortSignal
+    ): Promise<TwinFileGet>;
+    deleteTwinFile(
+        twinId: string,
+        fileId: string,
+        deleteRequest: TwinFileDelete,
+        signal?: AbortSignal
+    ): Promise<TwinFileGet>;
+
+    restoreTwinFile(twinId: string, fileId: string, etag: string, signal?: AbortSignal): Promise<TwinFileGet>;
+    getTwinFileContent(twinId: string, fileId: string, signal?: AbortSignal): Promise<Blob>;
+
+    getTwinFileVersion(twinId: string, fileId: string, version: number, signal?: AbortSignal): Promise<TwinFileGet>;
+    listTwinFileVersions(
+        twinId: string,
+        fileId: string,
+        options?: TwinFileVersionListOptions,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<TwinFileGet>>;
+
+    getTwinFileVersionContent(twinId: string, fileId: string, version: number, signal?: AbortSignal): Promise<Blob>;
+}
+
+export class TwinClient implements ITwinClient {
+    private readonly _baseUrl: string;
+
+    constructor(
+        baseUrl: string | URL,
+        private readonly _httpClient: TwinfinityHttpClient
+    ) {
+        this._baseUrl = `${baseUrl}/_ps/twins`;
+    }
+
+    async listTwins(
+        relatedTo?: string,
+        page: string | undefined = undefined,
+        limit = 100,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<ListTwinItem>> {
+        const params = new URLSearchParams();
+        if (relatedTo) params.set('relatedTo', relatedTo);
+        if (page !== undefined) params.set('page', page);
+        if (limit !== 100) params.set('limit', limit.toString());
+
+        const url = params.toString() ? `${this._baseUrl}?${params}` : this._baseUrl;
+
+        const response = await this._httpClient.fetch(HttpMethod.Get, url, {
+            headers: { 'Content-Type': 'application/json' },
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as PaginatedResponse<ListTwinItem>;
+        }
+
+        if (response.status === 400) {
+            const errorBody = await response.json();
+            throw new TwinValidationError(`Twin listing validation failed: ${errorBody.detail}`, errorBody);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to list twins: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async listAllTwins(relatedTo?: string, signal?: AbortSignal): Promise<ListTwinItem[]> {
+        const allTwins: ListTwinItem[] = [];
+        let page: string | undefined = undefined;
+        const limit = 100;
+        const maxPages = 1000;
+
+        for (let pageCount = 0; pageCount < maxPages; pageCount++) {
+            const response = await this.listTwins(relatedTo, page, limit, signal);
+            allTwins.push(...response.data);
+
+            if (response.data.length < limit) {
+                break;
+            }
+
+            page = response.pagination.nextPage;
+        }
+
+        return allTwins;
+    }
+
+    async getTwin(twin: string | { id: string; version: number }, signal?: AbortSignal): Promise<TwinGet> {
+        const twinId = typeof twin === 'string' ? twin : twin.id;
+        const specifiedVersion = typeof twin === 'string' ? undefined : twin.version;
+        const response = await this._httpClient.fetch(
+            HttpMethod.Get,
+            `${this._baseUrl}/${twinId}${specifiedVersion !== undefined ? `/versions/${specifiedVersion}` : ''}`,
+            {
+                headers: { 'Content-Type': 'application/json' },
+                signal
+            }
+        );
+
+        if (response.ok) {
+            return (await response.json()) as TwinGet;
+        }
+
+        if (response.status === 404) {
+            throw new TwinNotFoundError(`Twin ${twinId} not found`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to get twin: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async listTwinVersions(
+        id: string,
+        options?: {
+            includeDeleted?: boolean;
+            page: string | undefined;
+            limit?: number;
+        },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<ListTwinItem>> {
+        const params = new URLSearchParams();
+        if (options?.page !== undefined) params.set('page', options.page);
+        if (options?.limit !== undefined && options.limit !== 100) params.set('limit', options.limit.toString());
+        if (options?.includeDeleted) params.set('includeDeleted', 'true');
+
+        const url = `${this._baseUrl}/${id}/versions${params.toString() ? `?${params}` : ''}`;
+
+        const response = await this._httpClient.fetch(HttpMethod.Get, url, {
+            headers: { 'Content-Type': 'application/json' },
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as PaginatedResponse<ListTwinItem>;
+        }
+
+        if (response.status === 400) {
+            const errorBody = await response.json();
+            throw new TwinValidationError(`Twin listing validation failed: ${errorBody.detail}`, errorBody);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to list twins: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async downloadTwinContent(
+        twinId: string,
+        twinVersion: number,
+        content: TwinContentResponse,
+        signal?: AbortSignal
+    ): Promise<ArrayBuffer> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Get,
+            `${this._baseUrl}/${twinId}/versions/${twinVersion}/contents/${content.id}/content`,
+            { signal }
+        );
+        if (response.ok) {
+            const blob = await response.blob();
+            return await blob.arrayBuffer();
+        }
+
+        throw new Error(`Failed to download twin content: ${response.status} ${response.statusText}`);
+    }
+
+    private async loadTwinVersion<TProject, TProduct, TEntityType, TUnit>(
+        twinId: string,
+        twinVersion: number,
+        projectFactory: (dto: T8ClientProjectDTO<TUnit>) => TProject,
+        productFactory: (dto: T8ClientProductDTO<TUnit>) => TProduct,
+        entityTypeFactory: (dto: T8ClientEntityTypeDTO<TUnit>) => TEntityType,
+        unitFactory: (dto: T8ClientUnitDTO, dataModel: T8ClientModelDTO) => TUnit,
+        connectProject: (dto: T8ClientProjectConnectionsDTO<TProduct>, project: TProject) => void,
+        connectProduct: (dto: T8ClientProductConnectionsDTO<TProduct, TEntityType>, product: TProduct) => void,
+        signal?: AbortSignal
+    ): Promise<T8ClientModel<TProject, TProduct, TEntityType, TUnit> | undefined> {
+        const twinContent = await this.getTwinVersionContent(twinId, twinVersion, signal);
+
+        const t8cmItem = twinContent.content.find((item) => item.format === 't8cm');
+
+        if (t8cmItem === undefined) {
+            return undefined;
+        }
+
+        const t8cmExtensions = twinContent.content.filter((item) => item.format === 't8cm-ext');
+
+        const data = await Promise.all(
+            [this.downloadTwinContent(twinId, twinVersion, t8cmItem, signal)].concat(
+                t8cmExtensions.map((ext) => this.downloadTwinContent(twinId, twinVersion, ext, signal))
+            )
+        );
+
+        return readT8ClientModelWithFactories<TProject, TProduct, TEntityType, TUnit>(
+            data,
+            projectFactory,
+            productFactory,
+            entityTypeFactory,
+            unitFactory,
+            connectProject,
+            connectProduct
+        );
+    }
+
+    loadTwin(
+        twin: string | { id: string; version: number },
+        signal?: AbortSignal
+    ): Promise<Twin<T8Project, T8Product<T8EntityType>, T8EntityType, T8Unit>> {
+        return this.loadTwinWithFactories(
+            twin,
+            T8Project.create<T8Product<T8EntityType>, T8Unit>,
+            T8Product.create<T8EntityType, T8Unit>,
+            T8EntityType.create,
+            T8Unit.create,
+            T8Project.connect,
+            T8Product.connect,
+            signal
+        );
+    }
+
+    async loadTwinWithFactories<TProject, TProduct, TEntityType, TUnit>(
+        twin: string | { id: string; version: number },
+        projectFactory: (dto: T8ClientProjectDTO<TUnit>) => TProject,
+        productFactory: (dto: T8ClientProductDTO<TUnit>) => TProduct,
+        entityTypeFactory: (dto: T8ClientEntityTypeDTO<TUnit>) => TEntityType,
+        unitFactory: (dto: T8ClientUnitDTO, dataModel: T8ClientModelDTO) => TUnit,
+        connectProject: (dto: T8ClientProjectConnectionsDTO<TProduct>, project: TProject) => void,
+        connectProduct: (dto: T8ClientProductConnectionsDTO<TProduct, TEntityType>, product: TProduct) => void,
+        signal?: AbortSignal
+    ): Promise<Twin<TProject, TProduct, TEntityType, TUnit>> {
+        let page: string | undefined = undefined;
+        const twinId = typeof twin === 'string' ? twin : twin.id;
+        const specifiedVersion = typeof twin === 'string' ? undefined : twin.version;
+        if (specifiedVersion !== undefined) {
+            return {
+                id: twinId,
+                version: specifiedVersion,
+                model: await this.loadTwinVersion(
+                    twinId,
+                    specifiedVersion,
+                    projectFactory,
+                    productFactory,
+                    entityTypeFactory,
+                    unitFactory,
+                    connectProject,
+                    connectProduct,
+                    signal
+                )
+            };
+        }
+
+        const maxPages = 100;
+        for (let pageCount = 0; pageCount < maxPages; pageCount++) {
+            const versions = await this.listTwinVersions(twinId, { page }, signal);
+            if (versions.data.length === 0) {
+                break;
+            }
+            for (const versionItem of versions.data) {
+                const loadedModel = await this.loadTwinVersion(
+                    twinId,
+                    versionItem.version,
+                    projectFactory,
+                    productFactory,
+                    entityTypeFactory,
+                    unitFactory,
+                    connectProject,
+                    connectProduct,
+                    signal
+                );
+                if (loadedModel !== undefined) {
+                    return {
+                        id: twinId,
+                        version: versionItem.version,
+                        model: loadedModel
+                    };
+                }
+            }
+            page = versions.pagination.nextPage;
+        }
+
+        throw new Error(`Twin ${twinId} does not have a client model`);
+    }
+
+    private async loadGeometryInfoVersion<TMeshDescriptor, TStyle, TRegion>(
+        twinId: string,
+        twinVersion: number,
+        meshDescriptorFactory: (dto: T8GIMeshDescriptorDTO) => TMeshDescriptor,
+        styleFactory: (dto: T8GIStyleDTO) => TStyle,
+        regionFactory: (dto: T8GIRegionDTO) => TRegion,
+        signal?: AbortSignal
+    ): Promise<T8GIModelGeneric<TMeshDescriptor, TStyle, TRegion> | undefined> {
+        const twinContent = await this.getTwinVersionContent(twinId, twinVersion, signal);
+
+        const t8giItem = twinContent.content.find((item) => item.format === 't8gi');
+
+        if (t8giItem === undefined) {
+            return undefined;
+        }
+
+        const data = await this.downloadTwinContent(twinId, twinVersion, t8giItem, signal);
+
+        return readT8GIModelWithFactories(data, meshDescriptorFactory, styleFactory, regionFactory);
+    }
+
+    loadGeometryInfo(
+        twin: string | { id: string; version: number },
+        signal?: AbortSignal
+    ): Promise<TwinGeometryInfo<T8GIMeshDescriptor, T8GIStyle, T8GIRegion>> {
+        return this.loadGeometryInfoWithFactories(
+            twin,
+            T8GIMeshDescriptor.create,
+            T8GIStyle.create,
+            T8GIRegion.create,
+            signal
+        );
+    }
+
+    async loadGeometryInfoWithFactories<TMeshDescriptor, TStyle, TRegion>(
+        twin: string | { id: string; version: number },
+        meshDescriptorFactory: (dto: T8GIMeshDescriptorDTO) => TMeshDescriptor,
+        styleFactory: (dto: T8GIStyleDTO) => TStyle,
+        regionFactory: (dto: T8GIRegionDTO) => TRegion,
+        signal?: AbortSignal
+    ): Promise<TwinGeometryInfo<TMeshDescriptor, TStyle, TRegion>> {
+        let page: string | undefined = undefined;
+        const twinId = typeof twin === 'string' ? twin : twin.id;
+        const specifiedVersion = typeof twin === 'string' ? undefined : twin.version;
+
+        if (specifiedVersion !== undefined) {
+            return {
+                id: twinId,
+                version: specifiedVersion,
+                model: await this.loadGeometryInfoVersion(
+                    twinId,
+                    specifiedVersion,
+                    meshDescriptorFactory,
+                    styleFactory,
+                    regionFactory,
+                    signal
+                )
+            };
+        }
+
+        const maxPages = 100;
+        for (let pageCount = 0; pageCount < maxPages; pageCount++) {
+            const versions = await this.listTwinVersions(twinId, { page }, signal);
+            if (versions.data.length === 0) {
+                break;
+            }
+            for (const versionItem of versions.data) {
+                const model = await this.loadGeometryInfoVersion(
+                    twinId,
+                    versionItem.version,
+                    meshDescriptorFactory,
+                    styleFactory,
+                    regionFactory,
+                    signal
+                );
+                if (model !== undefined) {
+                    return {
+                        id: twinId,
+                        version: versionItem.version,
+                        model
+                    };
+                }
+            }
+            page = versions.pagination.nextPage;
+        }
+
+        throw new Error(`Twin ${twinId} does not have geometry info`);
+    }
+
+    async createOrUpdateTwin(twinId: string, twin: TwinPut, signal?: AbortSignal): Promise<TwinGet> {
+        const response = await this._httpClient.fetch(HttpMethod.Put, `${this._baseUrl}/${twinId}`, {
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(twin),
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as TwinGet;
+        }
+
+        if (response.status === 400) {
+            const errorBody = await response.json();
+            throw new TwinValidationError(`Twin validation failed: ${errorBody.detail}`, errorBody);
+        }
+
+        if (response.status === 409) {
+            const conflictedTwin = (await response.json()) as TwinGet;
+            throw new TwinConflictError('Twin has been modified by another user', conflictedTwin);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to create/update twin: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async updateTwin(twinId: string, twin: TwinPut, signal?: AbortSignal): Promise<TwinGet> {
+        return this.createOrUpdateTwin(twinId, twin, signal);
+    }
+
+    async deleteTwin(twinId: string, etag: string, signal?: AbortSignal): Promise<TwinGet> {
+        const response = await this._httpClient.fetch(HttpMethod.Delete, `${this._baseUrl}/${twinId}`, {
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ etag }),
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as TwinGet;
+        }
+
+        if (response.status === 404) {
+            throw new TwinNotFoundError(`Twin ${twinId} not found`);
+        }
+
+        if (response.status === 409) {
+            const conflictedTwin = (await response.json()) as TwinGet;
+            throw new TwinConflictError('Twin has been modified by another user', conflictedTwin);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to delete twin: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async restoreTwin(twinId: string, etag: string, signal?: AbortSignal): Promise<TwinGet> {
+        const response = await this._httpClient.fetch(HttpMethod.Put, `${this._baseUrl}/${twinId}/restore`, {
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ etag }),
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as TwinGet;
+        }
+
+        if (response.status === 404) {
+            throw new TwinNotFoundError(`Twin ${twinId} not found`);
+        }
+
+        if (response.status === 409) {
+            const conflictedTwin = (await response.json()) as TwinGet;
+            throw new TwinConflictError('Twin has been modified by another user', conflictedTwin);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to restore twin: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async getTwinVersionContent(
+        twinId: string,
+        twinVersion: number,
+        signal?: AbortSignal
+    ): Promise<TwinVersionContentResponse> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Get,
+            `${this._baseUrl}/${twinId}/versions/${twinVersion}/contents`,
+            { headers: { 'Content-Type': 'application/json' }, signal }
+        );
+
+        if (response.ok) {
+            return (await response.json()) as TwinVersionContentResponse;
+        }
+
+        if (response.status === 404) {
+            throw new TwinNotFoundError(`Twin ${twinId} version ${twinVersion} not found`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to get twin version content: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async getTwinContent(twinId: string, signal?: AbortSignal): Promise<TwinVersionContentResponse> {
+        const response = await this._httpClient.fetch(HttpMethod.Get, `${this._baseUrl}/${twinId}/contents`, {
+            headers: { 'Content-Type': 'application/json' },
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as TwinVersionContentResponse;
+        }
+
+        if (response.status === 404) {
+            throw new TwinNotFoundError(`Twin ${twinId} not found`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to get twin content: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async getTwinDiagnostics(twinId: string, signal?: AbortSignal): Promise<TwinDiagnosticsResponse> {
+        const response = await this._httpClient.fetch(HttpMethod.Get, `${this._baseUrl}/${twinId}/diagnostics`, {
+            headers: { 'Content-Type': 'application/json' },
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as TwinDiagnosticsResponse;
+        }
+
+        if (response.status === 404) {
+            throw new TwinNotFoundError(`Twin ${twinId} not found`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to get twin diagnostics: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async getTwinVersionDiagnostics(
+        twinId: string,
+        twinVersion: number,
+        signal?: AbortSignal
+    ): Promise<TwinDiagnosticsResponse> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Get,
+            `${this._baseUrl}/${twinId}/versions/${twinVersion}/diagnostics`,
+            { headers: { 'Content-Type': 'application/json' }, signal }
+        );
+
+        if (response.ok) {
+            return (await response.json()) as TwinDiagnosticsResponse;
+        }
+
+        if (response.status === 404) {
+            throw new TwinNotFoundError(`Twin ${twinId} version ${twinVersion} not found`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(
+            `Failed to get twin version diagnostics: ${response.status} ${response.statusText} - ${errorText}`
+        );
+    }
+
+    async getTwinVersionEvents(
+        twinId: string,
+        twinVersion: number,
+        offset = 0,
+        limit = 100,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<TwinProcessorEvent>> {
+        const url = `${this._baseUrl}/${twinId}/versions/${twinVersion}/events?offset=${offset}&limit=${limit}`;
+
+        const response = await this._httpClient.fetch(HttpMethod.Get, url, {
+            headers: { 'Content-Type': 'application/json' },
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as PaginatedResponse<TwinProcessorEvent>;
+        }
+
+        if (response.status === 400) {
+            const errorBody = await response.json();
+            throw new TwinValidationError(`Twin events validation failed: ${errorBody.detail}`, errorBody);
+        }
+
+        if (response.status === 404) {
+            throw new TwinNotFoundError(`Twin ${twinId} version ${twinVersion} not found`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to get twin version events: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async getProcessorEvents(
+        twinId: string,
+        twinVersion: number,
+        processorId: string,
+        offset = 0,
+        limit = 100,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<TwinProcessorEvent>> {
+        const url = `${this._baseUrl}/${twinId}/versions/${twinVersion}/processors/${processorId}/events?offset=${offset}&limit=${limit}`;
+
+        const response = await this._httpClient.fetch(HttpMethod.Get, url, {
+            headers: { 'Content-Type': 'application/json' },
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as PaginatedResponse<TwinProcessorEvent>;
+        }
+
+        if (response.status === 400) {
+            const errorBody = await response.json();
+            throw new TwinValidationError(`Processor events validation failed: ${errorBody.detail}`, errorBody);
+        }
+
+        if (response.status === 404) {
+            throw new ProcessorNotFoundError(
+                `Processor ${processorId} not found for twin ${twinId} version ${twinVersion}`
+            );
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to get processor events: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async listAssets(
+        twinId: string,
+        offset = 0,
+        limit = 100,
+        options?: { includeDeleted?: boolean },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<AssetListItem>> {
+        const includeDeleted = options?.includeDeleted ?? false;
+        const params = `offset=${offset}&limit=${limit}${includeDeleted ? '&includeDeleted=true' : ''}`;
+        const response = await this._httpClient.fetch(HttpMethod.Get, `${this._baseUrl}/${twinId}/assets?${params}`, {
+            headers: { 'Content-Type': 'application/json' },
+            signal
+        });
+
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Failed to list assets: ${response.status} ${response.statusText} - ${errorText}`);
+        }
+
+        return (await response.json()) as PaginatedResponse<AssetListItem>;
+    }
+
+    async getAsset(twinId: string, assetId: string, signal?: AbortSignal): Promise<AssetGet> {
+        const response = await this._httpClient.fetch(HttpMethod.Get, `${this._baseUrl}/${twinId}/assets/${assetId}`, {
+            headers: { 'Content-Type': 'application/json' },
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as AssetGet;
+        }
+
+        if (response.status === 404) {
+            throw new AssetNotFoundError(`Asset ${assetId} not found`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to get asset: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async createAssets(twinId: string, assets: AssetPost[], signal?: AbortSignal): Promise<AssetGet[]> {
+        const response = await this._httpClient.fetch(HttpMethod.Post, `${this._baseUrl}/${twinId}/assets`, {
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(assets),
+            signal
+        });
+
+        if (response.status === 201) {
+            return (await response.json()) as AssetGet[];
+        }
+
+        if (response.status === 400) {
+            const errorText = await response.text();
+            throw new AssetValidationError(`Asset validation failed: ${errorText}`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to create assets: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async updateAsset(twinId: string, assetId: string, asset: AssetPut, signal?: AbortSignal): Promise<AssetGet> {
+        const response = await this._httpClient.fetch(HttpMethod.Put, `${this._baseUrl}/${twinId}/assets/${assetId}`, {
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(asset),
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as AssetGet;
+        }
+
+        if (response.status === 409) {
+            const conflictedAsset = (await response.json()) as AssetGet;
+            throw new AssetConflictError('Asset has been modified by another user', conflictedAsset);
+        }
+
+        if (response.status === 400) {
+            const errorText = await response.text();
+            throw new AssetValidationError(`Asset validation failed: ${errorText}`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to update asset: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async deleteAsset(twinId: string, assetId: string, etag: string, signal?: AbortSignal): Promise<AssetGet> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Delete,
+            `${this._baseUrl}/${twinId}/assets/${assetId}`,
+            {
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ etag }),
+                signal
+            }
+        );
+
+        if (response.ok) {
+            return (await response.json()) as AssetGet;
+        }
+
+        if (response.status === 409) {
+            const conflictedAsset = (await response.json()) as AssetGet;
+            throw new AssetConflictError('Asset has been modified by another user', conflictedAsset);
+        }
+
+        if (response.status === 404) {
+            throw new AssetNotFoundError(`Asset ${assetId} not found`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to delete asset: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    /**
+     * Restores a soft-deleted asset.
+     *
+     * @param twinId - The twin ID
+     * @param assetId - The asset ID to restore
+     * @param etag - The current etag of the deleted asset
+     * @returns The restored asset
+     * @throws {AssetConflictError} When the asset has been modified (409)
+     * @throws {AssetNotFoundError} When the asset does not exist (404)
+     */
+    async restoreAsset(twinId: string, assetId: string, etag: string): Promise<AssetGet> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Put,
+            `${this._baseUrl}/${twinId}/assets/${assetId}/restore`,
+            {
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ etag })
+            }
+        );
+
+        if (response.ok) {
+            return (await response.json()) as AssetGet;
+        }
+
+        if (response.status === 409) {
+            const conflictedAsset = (await response.json()) as AssetGet;
+            throw new AssetConflictError('Asset has been modified by another user', conflictedAsset);
+        }
+
+        if (response.status === 404) {
+            throw new AssetNotFoundError(`Asset ${assetId} not found`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to restore asset: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    /**
+     * Executes a batch of asset operations (upsert, delete, restore) atomically.
+     * All operations succeed or all are rolled back.
+     *
+     * @param twinId - The twin ID
+     * @param operations - Array of batch operations (max 1000)
+     * @returns Batch response with results for each operation
+     * @throws {AssetValidationError} When request validation fails (400) or insufficient permissions (403)
+     * @throws {AssetBatchError} When an operation conflicts (409) or asset not found (404) — the response contains per-item results with reverted statuses
+     */
+    async batchAssets(twinId: string, operations: AssetBatchOperation[]): Promise<AssetBatchResponse> {
+        const response = await this._httpClient.fetch(HttpMethod.Post, `${this._baseUrl}/${twinId}/assets/batch`, {
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ operations })
+        });
+
+        if (response.ok) {
+            return (await response.json()) as AssetBatchResponse;
+        }
+
+        if (response.status === 400) {
+            const errorText = await response.text();
+            throw new AssetValidationError(`Asset batch validation failed: ${errorText}`);
+        }
+
+        if (response.status === 403) {
+            const errorText = await response.text();
+            throw new AssetValidationError(`Asset batch forbidden: ${errorText}`);
+        }
+
+        if (response.status === 404 || response.status === 409) {
+            const batchResponse = (await response.json()) as AssetBatchResponse;
+            throw new AssetBatchError(`Asset batch operation failed with status ${response.status}`, batchResponse);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to execute asset batch: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    /**
+     * Retrieves multiple assets by their IDs in a single request.
+     *
+     * @param twinId - The twin ID
+     * @param ids - Array of asset IDs to retrieve (max 1000)
+     * @returns Batch response with summary and per-item results
+     * @throws {AssetValidationError} When request validation fails (400)
+     */
+    async batchGetAssets(twinId: string, ids: string[]): Promise<AssetBatchGetResponse> {
+        const response = await this._httpClient.fetch(HttpMethod.Post, `${this._baseUrl}/${twinId}/assets/batch-get`, {
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ ids })
+        });
+
+        if (response.ok) {
+            return (await response.json()) as AssetBatchGetResponse;
+        }
+
+        if (response.status === 400) {
+            const errorText = await response.text();
+            throw new AssetValidationError(`Asset batch-get validation failed: ${errorText}`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to batch-get assets: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async listTwinFiles(
+        twinId: string,
+        options: TwinFileListOptions = {},
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<TwinFileGet>> {
+        const { includeDeleted = false, checkedIn = false, version, page = undefined, limit = 100 } = options;
+
+        if (version !== undefined && !checkedIn) {
+            throw new Error('The "version" option can only be used when "checkedIn" is true.');
+        }
+
+        const params = new URLSearchParams();
+        if (includeDeleted) params.set('includeDeleted', 'true');
+        if (checkedIn) params.set('checkedIn', 'true');
+        if (version !== undefined) params.set('version', version.toString());
+        if (page !== undefined) params.set('page', page);
+        if (limit !== 100) params.set('limit', limit.toString());
+
+        const url = params.toString()
+            ? `${this._baseUrl}/${twinId}/files?${params}`
+            : `${this._baseUrl}/${twinId}/files`;
+
+        const response = await this._httpClient.fetch(HttpMethod.Get, url, {
+            headers: { 'Content-Type': 'application/json' },
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as PaginatedResponse<TwinFileGet>;
+        }
+
+        if (response.status === 400) {
+            const errorBody = await response.json();
+            throw new TwinFileValidationError(`Twin file listing validation failed: ${errorBody.detail}`, errorBody);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to list twin files: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async getTwinFile(twinId: string, fileId: string, signal?: AbortSignal): Promise<TwinFileGet> {
+        const response = await this._httpClient.fetch(HttpMethod.Get, `${this._baseUrl}/${twinId}/files/${fileId}`, {
+            headers: { 'Content-Type': 'application/json' },
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as TwinFileGet;
+        }
+
+        if (response.status === 404) {
+            throw new TwinFileNotFoundError(`Twin file ${fileId} not found`);
+        }
+
+        if (response.status === 400) {
+            const errorText = await response.text();
+            throw new TwinFileValidationError(`Twin file validation failed: ${errorText}`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to get twin file: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async createOrUpdateTwinFile(
+        twinId: string,
+        fileId: string,
+        twinFile: TwinFilePut,
+        signal?: AbortSignal
+    ): Promise<TwinFileGet> {
+        const response = await this._httpClient.fetch(HttpMethod.Put, `${this._baseUrl}/${twinId}/files/${fileId}`, {
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(twinFile),
+            signal
+        });
+
+        if (response.ok || response.status === 201) {
+            return (await response.json()) as TwinFileGet;
+        }
+
+        if (response.status === 400) {
+            const errorBody = await response.json();
+            throw new TwinFileValidationError(`Twin file validation failed`, errorBody);
+        }
+
+        if (response.status === 409) {
+            const conflictedFile = (await response.json()) as TwinFileGet;
+            throw new TwinFileConflictError('Twin file has been modified by another user', conflictedFile);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to create/update twin file: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async deleteTwinFile(
+        twinId: string,
+        fileId: string,
+        deleteRequest: TwinFileDelete,
+        signal?: AbortSignal
+    ): Promise<TwinFileGet> {
+        const response = await this._httpClient.fetch(HttpMethod.Delete, `${this._baseUrl}/${twinId}/files/${fileId}`, {
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(deleteRequest),
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as TwinFileGet;
+        }
+
+        if (response.status === 404) {
+            throw new TwinFileNotFoundError(`Twin file ${fileId} not found`);
+        }
+
+        if (response.status === 409) {
+            const conflictedFile = (await response.json()) as TwinFileGet;
+            throw new TwinFileConflictError('Twin file has been modified by another user', conflictedFile);
+        }
+
+        if (response.status === 400) {
+            const errorText = await response.text();
+            throw new TwinFileValidationError(`Twin file validation failed: ${errorText}`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to delete twin file: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async restoreTwinFile(twinId: string, fileId: string, etag: string, signal?: AbortSignal): Promise<TwinFileGet> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Put,
+            `${this._baseUrl}/${twinId}/files/${fileId}/restore`,
+            {
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ etag }),
+                signal
+            }
+        );
+
+        if (response.ok) {
+            return (await response.json()) as TwinFileGet;
+        }
+
+        if (response.status === 404) {
+            throw new TwinFileNotFoundError(`Twin file ${fileId} not found`);
+        }
+
+        if (response.status === 409) {
+            const conflictedFile = (await response.json()) as TwinFileGet;
+            throw new TwinFileConflictError('Twin file has been modified by another user', conflictedFile);
+        }
+
+        if (response.status === 400) {
+            const errorText = await response.text();
+            throw new TwinFileValidationError(`Twin file validation failed: ${errorText}`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to restore twin file: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async getTwinFileContent(twinId: string, fileId: string, signal?: AbortSignal): Promise<Blob> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Get,
+            `${this._baseUrl}/${twinId}/files/${fileId}/content`,
+            { signal }
+        );
+
+        if (response.ok) {
+            return await response.blob();
+        }
+
+        if (response.status === 404) {
+            throw new TwinFileNotFoundError(`Twin file ${fileId} not found`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to get twin file content: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async getTwinFileVersion(
+        twinId: string,
+        fileId: string,
+        version: number,
+        signal?: AbortSignal
+    ): Promise<TwinFileGet> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Get,
+            `${this._baseUrl}/${twinId}/files/${fileId}/versions/${version}`,
+            { signal }
+        );
+
+        if (response.ok) {
+            return (await response.json()) as TwinFileGet;
+        }
+
+        if (response.status === 404) {
+            throw new TwinFileNotFoundError(`Twin file ${fileId} version ${version} not found`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to get twin file version: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async listTwinFileVersions(
+        twinId: string,
+        fileId: string,
+        options?: TwinFileVersionListOptions,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<TwinFileGet>> {
+        const params = new URLSearchParams();
+        if (options?.includeDeleted !== undefined) params.append('includeDeleted', String(options.includeDeleted));
+        if (options?.offset !== undefined) params.append('offset', String(options.offset));
+        if (options?.limit !== undefined) params.append('limit', String(options.limit));
+
+        const response = await this._httpClient.fetch(
+            HttpMethod.Get,
+            `${this._baseUrl}/${twinId}/files/${fileId}/versions?${params.toString()}`,
+            { signal }
+        );
+
+        if (response.ok) {
+            return (await response.json()) as PaginatedResponse<TwinFileGet>;
+        }
+
+        if (response.status === 400) {
+            const errorBody = await response.json();
+            throw new Error(`Bad request: ${errorBody.detail || response.statusText}`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to list twin file versions: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async getTwinFileVersionContent(
+        twinId: string,
+        fileId: string,
+        version: number,
+        signal?: AbortSignal
+    ): Promise<Blob> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Get,
+            `${this._baseUrl}/${twinId}/files/${fileId}/versions/${version}/content`,
+            { signal }
+        );
+
+        if (response.ok) {
+            return await response.blob();
+        }
+
+        if (response.status === 404) {
+            throw new TwinFileNotFoundError(`Twin file ${fileId} version ${version} content not found`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(
+            `Failed to get twin file version content: ${response.status} ${response.statusText} - ${errorText}`
+        );
+    }
+
+    async createOrUpdateTwinRaw(twinId: string, twin: unknown, signal?: AbortSignal): Promise<Response> {
+        return await this._httpClient.fetch(HttpMethod.Put, `${this._baseUrl}/${twinId}`, {
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(twin),
+            signal
+        });
+    }
+
+    async createOrUpdateTwinFileRaw(
+        twinId: string,
+        fileId: string,
+        twinFile: unknown,
+        signal?: AbortSignal
+    ): Promise<Response> {
+        return await this._httpClient.fetch(HttpMethod.Put, `${this._baseUrl}/${twinId}/files/${fileId}`, {
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(twinFile),
+            signal
+        });
+    }
+}