@twinfinity/twin 6.0.1 → 6.0.2

package/src/TwinClient.ts

@@ -1,1496 +1,2334 @@
-import { TwinfinityHttpClient, HttpMethod } from '@twinfinity/authentication';
-import {
-    readT8ClientModelWithFactories,
-    readT8ClientModelWithGeometry,
-    readT8GIModelWithFactories,
-    T8ClientEntityTypeDTO,
-    T8ClientModel,
-    T8ClientModelDTO,
-    T8ClientProductConnectionsDTO,
-    T8ClientProductDTO,
-    T8ClientProjectConnectionsDTO,
-    T8ClientProjectDTO,
-    T8ClientUnitDTO,
-    T8EntityType,
-    T8GIMeshDescriptor,
-    T8GIMeshDescriptorDTO,
-    T8GIStyle,
-    T8GIStyleDTO,
-    T8GIRegion,
-    T8GIRegionDTO,
-    T8Product,
-    T8ProductWithGeometry,
-    T8Project,
-    T8Unit
-} from '@twinfinity/t8-client-model';
-import type { T8ProjectWithGeometry } 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,
-    AssetForbiddenError,
-    AssetConflictError,
-    AssetNotFoundError,
-    AssetBatchError,
-    TwinFileValidationError,
-    TwinFileConflictError,
-    TwinFileNotFoundError
-} from './errors';
-import { Twin } from './types/Twin';
-import { TwinGeometryInfo } from './types/TwinGeometryInfo';
-
-export interface ITwinClient {
-    /**
-     * @param relatedTo - Filter twins by container ID.
-     * @throws {TwinValidationError} On invalid query parameters (400).
-     */
-    listTwins(
-        relatedTo?: string,
-        page?: string,
-        limit?: number,
-        signal?: AbortSignal
-    ): Promise<PaginatedResponse<ListTwinItem>>;
-
-    /**
-     * Fetches all twins by auto-paginating through {@link listTwins}. Caps at 1000 pages.
-     * @param relatedTo - Filter twins by container ID.
-     */
-    listAllTwins(relatedTo?: string, signal?: AbortSignal): Promise<ListTwinItem[]>;
-
-    /**
-     * @param twin - Twin ID string, or `{id, version}` to fetch a specific version.
-     * @throws {TwinNotFoundError} When the twin or version does not exist (404).
-     */
-    getTwin(twin: string | { id: string; version: number }, signal?: AbortSignal): Promise<TwinGet>;
-
-    /**
-     * @throws {TwinValidationError} On invalid query parameters (400).
-     */
-    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>;
-
-    /**
-     * Downloads and deserializes the T8 client model (t8cm + t8cm-ext) using default types.
-     * When no version is specified, searches versions newest-first for one containing t8cm content.
-     *
-     * @param twin - Twin ID string, or `{id, version}` to load a specific version.
-     * @throws {Error} When no version has t8cm content.
-     */
-    loadTwin(
-        twin: string | { id: string; version: number },
-        signal?: AbortSignal
-    ): Promise<Twin<T8Project, T8Product<T8EntityType>, T8EntityType, T8Unit>>;
-
-    /**
-     * Downloads and deserializes the T8 client model using custom factory functions for domain-specific types.
-     * When no version is specified, searches versions newest-first for one containing t8cm content.
-     *
-     * @param twin - Twin ID string, or `{id, version}` to load a specific version.
-     * @throws {Error} When no version has t8cm content.
-     */
-    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>>;
-
-    /**
-     * Downloads and deserializes geometry info (t8gi) using default types.
-     * When no version is specified, searches versions newest-first for one containing t8gi content.
-     *
-     * @param twin - Twin ID string, or `{id, version}` to load a specific version.
-     * @throws {Error} When no version has t8gi content.
-     */
-    loadGeometryInfo(
-        twin: string | { id: string; version: number },
-        signal?: AbortSignal
-    ): Promise<TwinGeometryInfo<T8GIMeshDescriptor, T8GIStyle, T8GIRegion>>;
-
-    /**
-     * Downloads and deserializes geometry info (t8gi) using custom factory functions.
-     * When no version is specified, searches versions newest-first for one containing t8gi content.
-     *
-     * @param twin - Twin ID string, or `{id, version}` to load a specific version.
-     * @throws {Error} When no version has t8gi content.
-     */
-    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>>;
-
-    /**
-     * Downloads and deserializes both the client model (t8cm) and geometry (t8gi/t8gd) into a combined result.
-     * When no version is specified, searches versions newest-first for one containing both t8cm and t8gi content.
-     *
-     * @param twin - Twin ID string, or `{id, version}` to load a specific version.
-     * @throws {Error} When no version has both t8cm and t8gi content.
-     */
-    loadTwinWithGeometry(
-        twin: string | { id: string; version: number },
-        signal?: AbortSignal
-    ): Promise<Twin<T8ProjectWithGeometry, T8ProductWithGeometry, T8EntityType, T8Unit>>;
-
-    /**
-     * Creates a new twin or updates an existing one (upsert). Provide `etag` in the twin body to update.
-     *
-     * @throws {TwinValidationError} On invalid request body (400).
-     * @throws {TwinConflictError} On etag mismatch (409). The error's `currentTwin` contains the server's current state.
-     */
-    createOrUpdateTwin(twinId: string, twin: TwinPut, signal?: AbortSignal): Promise<TwinGet>;
-
-    /** Alias for {@link createOrUpdateTwin}. */
-    updateTwin(twinId: string, twin: TwinPut, signal?: AbortSignal): Promise<TwinGet>;
-
-    /**
-     * @throws {TwinNotFoundError} When the twin does not exist (404).
-     * @throws {TwinConflictError} On etag mismatch (409). The error's `currentTwin` contains the server's current state.
-     */
-    restoreTwin(twinId: string, etag: string, signal?: AbortSignal): Promise<TwinGet>;
-
-    /**
-     * @throws {TwinNotFoundError} When the twin or version does not exist (404).
-     */
-    getTwinVersionContent(
-        twinId: string,
-        twinVersion: number,
-        signal?: AbortSignal
-    ): Promise<TwinVersionContentResponse>;
-
-    /**
-     * Returns content for the latest twin version.
-     * @throws {TwinNotFoundError} When the twin does not exist (404).
-     */
-    getTwinContent(twinId: string, signal?: AbortSignal): Promise<TwinVersionContentResponse>;
-
-    /** @throws {TwinNotFoundError} When the twin does not exist (404). */
-    getTwinDiagnostics(twinId: string, signal?: AbortSignal): Promise<TwinDiagnosticsResponse>;
-
-    /** @throws {TwinNotFoundError} When the twin or version does not exist (404). */
-    getTwinVersionDiagnostics(
-        twinId: string,
-        twinVersion: number,
-        signal?: AbortSignal
-    ): Promise<TwinDiagnosticsResponse>;
-
-    /**
-     * @throws {TwinValidationError} On invalid query parameters (400).
-     * @throws {TwinNotFoundError} When the twin or version does not exist (404).
-     */
-    getTwinVersionEvents(
-        twinId: string,
-        twinVersion: number,
-        offset?: number,
-        limit?: number,
-        signal?: AbortSignal
-    ): Promise<PaginatedResponse<TwinProcessorEvent>>;
-
-    /**
-     * @throws {TwinValidationError} On invalid query parameters (400).
-     * @throws {ProcessorNotFoundError} When the processor does not exist for this twin version (404).
-     */
-    getProcessorEvents(
-        twinId: string,
-        twinVersion: number,
-        processorId: string,
-        offset?: number,
-        limit?: number,
-        signal?: AbortSignal
-    ): Promise<PaginatedResponse<TwinProcessorEvent>>;
-
-    /**
-     * @throws {AssetValidationError} On invalid query parameters (400).
-     * @throws {AssetNotFoundError} When the twin does not exist (404).
-     */
-    listAssets(
-        twinId: string,
-        offset?: number,
-        limit?: number,
-        options?: { includeDeleted?: boolean },
-        signal?: AbortSignal
-    ): Promise<PaginatedResponse<AssetListItem>>;
-
-    /** @throws {AssetNotFoundError} When the asset does not exist (404). */
-    getAsset(twinId: string, assetId: string, signal?: AbortSignal): Promise<AssetGet>;
-
-    /** @throws {AssetValidationError} On invalid request body (400). The error's `errorBody` has structured detail. */
-    createAssets(twinId: string, assets: AssetPost[], signal?: AbortSignal): Promise<AssetGet[]>;
-
-    /**
-     * @throws {AssetValidationError} On invalid request body (400). The error's `errorBody` has structured detail.
-     * @throws {AssetConflictError} On etag mismatch (409). The error's `currentAsset` contains the server's current state.
-     */
-    updateAsset(twinId: string, assetId: string, asset: AssetPut, signal?: AbortSignal): Promise<AssetGet>;
-
-    /**
-     * @throws {AssetNotFoundError} When the asset does not exist (404).
-     * @throws {AssetConflictError} On etag mismatch (409). The error's `currentAsset` contains the server's current state.
-     */
-    deleteAsset(twinId: string, assetId: string, etag: string, signal?: AbortSignal): Promise<AssetGet>;
-
-    /**
-     * @throws {AssetNotFoundError} When the asset does not exist (404).
-     * @throws {AssetConflictError} On etag mismatch (409). The error's `currentAsset` contains the server's current state.
-     */
-    restoreAsset(twinId: string, assetId: string, etag: string, signal?: AbortSignal): Promise<AssetGet>;
-
-    /**
-     * Executes a batch of asset operations (upsert, delete, restore) atomically.
-     * All operations succeed or all are rolled back.
-     *
-     * @param operations - Array of batch operations (max 1000).
-     * @throws {AssetValidationError} On validation failure (400).
-     * @throws {AssetForbiddenError} On insufficient permissions (403).
-     * @throws {AssetBatchError} On conflict (409) or not found (404). The error's `response` has per-item results with reverted statuses.
-     */
-    batchAssets(twinId: string, operations: AssetBatchOperation[], signal?: AbortSignal): Promise<AssetBatchResponse>;
-
-    /**
-     * Retrieves multiple assets by ID in a single request.
-     *
-     * @param ids - Array of asset IDs (max 1000).
-     * @throws {AssetValidationError} On validation failure (400).
-     */
-    batchGetAssets(twinId: string, ids: string[], signal?: AbortSignal): Promise<AssetBatchGetResponse>;
-
-    /**
-     * @throws {TwinNotFoundError} When the twin does not exist (404).
-     * @throws {TwinConflictError} On etag mismatch (409). The error's `currentTwin` contains the server's current state.
-     */
-    deleteTwin(twinId: string, etag: string, signal?: AbortSignal): Promise<TwinGet>;
-
-    /** @throws {TwinFileValidationError} On invalid query parameters (400). */
-    listTwinFiles(
-        twinId: string,
-        options?: TwinFileListOptions,
-        signal?: AbortSignal
-    ): Promise<PaginatedResponse<TwinFileGet>>;
-
-    /**
-     * @throws {TwinFileNotFoundError} When the file does not exist (404).
-     * @throws {TwinFileValidationError} On invalid request (400).
-     */
-    getTwinFile(twinId: string, fileId: string, signal?: AbortSignal): Promise<TwinFileGet>;
-
-    /**
-     * @throws {TwinFileValidationError} On invalid request body (400).
-     * @throws {TwinFileConflictError} On etag mismatch (409). The error's `currentTwinFile` contains the server's current state.
-     */
-    createOrUpdateTwinFile(
-        twinId: string,
-        fileId: string,
-        twinFile: TwinFilePut,
-        signal?: AbortSignal
-    ): Promise<TwinFileGet>;
-
-    /**
-     * @throws {TwinFileNotFoundError} When the file does not exist (404).
-     * @throws {TwinFileConflictError} On etag mismatch (409). The error's `currentTwinFile` contains the server's current state.
-     * @throws {TwinFileValidationError} On invalid request (400).
-     */
-    deleteTwinFile(
-        twinId: string,
-        fileId: string,
-        deleteRequest: TwinFileDelete,
-        signal?: AbortSignal
-    ): Promise<TwinFileGet>;
-
-    /**
-     * @throws {TwinFileNotFoundError} When the file does not exist (404).
-     * @throws {TwinFileConflictError} On etag mismatch (409). The error's `currentTwinFile` contains the server's current state.
-     * @throws {TwinFileValidationError} On invalid request (400).
-     */
-    restoreTwinFile(twinId: string, fileId: string, etag: string, signal?: AbortSignal): Promise<TwinFileGet>;
-
-    /** @throws {TwinFileNotFoundError} When the file does not exist (404). */
-    getTwinFileContent(twinId: string, fileId: string, signal?: AbortSignal): Promise<Blob>;
-
-    /** @throws {TwinFileNotFoundError} When the file or version does not exist (404). */
-    getTwinFileVersion(twinId: string, fileId: string, version: number, signal?: AbortSignal): Promise<TwinFileGet>;
-
-    /** @throws {TwinFileValidationError} On invalid query parameters (400). */
-    listTwinFileVersions(
-        twinId: string,
-        fileId: string,
-        options?: TwinFileVersionListOptions,
-        signal?: AbortSignal
-    ): Promise<PaginatedResponse<TwinFileGet>>;
-
-    /** @throws {TwinFileNotFoundError} When the file or version does not exist (404). */
-    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`);
-    }
-
-    private async loadTwinWithGeometryVersion(
-        twinId: string,
-        twinVersion: number,
-        signal?: AbortSignal
-    ): Promise<T8ClientModel<T8ProjectWithGeometry, T8ProductWithGeometry, T8EntityType, T8Unit> | undefined> {
-        const twinContent = await this.getTwinVersionContent(twinId, twinVersion, signal);
-
-        const t8cmItem = twinContent.content.find((item) => item.format === 't8cm');
-        const t8giItem = twinContent.content.find((item) => item.format === 't8gi');
-
-        if (t8cmItem === undefined || t8giItem === undefined) {
-            return undefined;
-        }
-
-        const t8cmExtensions = twinContent.content.filter((item) => item.format === 't8cm-ext');
-        const t8gdItem = twinContent.content.find((item) => item.format === 't8gd');
-
-        const downloads = [
-            this.downloadTwinContent(twinId, twinVersion, t8cmItem, signal),
-            ...t8cmExtensions.map((ext) => this.downloadTwinContent(twinId, twinVersion, ext, signal)),
-            this.downloadTwinContent(twinId, twinVersion, t8giItem, signal),
-            ...(t8gdItem ? [this.downloadTwinContent(twinId, twinVersion, t8gdItem, signal)] : [])
-        ];
-
-        const allData = await Promise.all(downloads);
-
-        const t8cmCount = 1 + t8cmExtensions.length;
-        const t8cmData = allData.slice(0, t8cmCount);
-        const t8giData = allData[t8cmCount];
-        const t8gdData = t8gdItem ? allData[t8cmCount + 1] : undefined;
-
-        return readT8ClientModelWithGeometry(t8cmData, t8giData, t8gdData);
-    }
-
-    async loadTwinWithGeometry(
-        twin: string | { id: string; version: number },
-        signal?: AbortSignal
-    ): Promise<Twin<T8ProjectWithGeometry, T8ProductWithGeometry, T8EntityType, T8Unit>> {
-        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.loadTwinWithGeometryVersion(twinId, specifiedVersion, 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.loadTwinWithGeometryVersion(twinId, versionItem.version, signal);
-                if (model !== undefined) {
-                    return {
-                        id: twinId,
-                        version: versionItem.version,
-                        model
-                    };
-                }
-            }
-            page = versions.pagination.nextPage;
-        }
-
-        throw new Error(`Twin ${twinId} does not have a client model with geometry`);
-    }
-
-    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) {
-            return (await response.json()) as PaginatedResponse<AssetListItem>;
-        }
-
-        if (response.status === 400) {
-            const errorBody = await response.json();
-            throw new AssetValidationError(`Asset listing validation failed: ${errorBody.detail}`, errorBody);
-        }
-
-        if (response.status === 404) {
-            throw new AssetNotFoundError(`Twin ${twinId} not found`);
-        }
-
-        const errorText = await response.text();
-        throw new Error(`Failed to list assets: ${response.status} ${response.statusText} - ${errorText}`);
-    }
-
-    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 errorBody = await response.json();
-            throw new AssetValidationError(`Asset validation failed: ${errorBody.detail}`, errorBody);
-        }
-
-        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 errorBody = await response.json();
-            throw new AssetValidationError(`Asset validation failed: ${errorBody.detail}`, errorBody);
-        }
-
-        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}`);
-    }
-
-    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}`);
-    }
-
-    async batchAssets(
-        twinId: string,
-        operations: AssetBatchOperation[],
-        signal?: AbortSignal
-    ): Promise<AssetBatchResponse> {
-        const response = await this._httpClient.fetch(HttpMethod.Post, `${this._baseUrl}/${twinId}/assets/batch`, {
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ operations }),
-            signal
-        });
-
-        if (response.ok) {
-            return (await response.json()) as AssetBatchResponse;
-        }
-
-        if (response.status === 400) {
-            const errorBody = await response.json();
-            throw new AssetValidationError(`Asset batch validation failed: ${errorBody.detail}`, errorBody);
-        }
-
-        if (response.status === 403) {
-            const errorText = await response.text();
-            throw new AssetForbiddenError(`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}`);
-    }
-
-    async batchGetAssets(twinId: string, ids: string[], signal?: AbortSignal): 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 }),
-            signal
-        });
-
-        if (response.ok) {
-            return (await response.json()) as AssetBatchGetResponse;
-        }
-
-        if (response.status === 400) {
-            const errorBody = await response.json();
-            throw new AssetValidationError(`Asset batch-get validation failed: ${errorBody.detail}`, errorBody);
-        }
-
-        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 TwinFileValidationError(
-                `Twin file version listing validation failed: ${errorBody.detail}`,
-                errorBody
-            );
-        }
-
-        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
-        });
-    }
-}
+import { TwinfinityHttpClient, HttpMethod } from '@twinfinity/authentication';
+import {
+    readT8ClientModelWithFactories,
+    readT8ClientModelWithGeometry,
+    readT8GIModelWithFactories,
+    T8ClientEntityTypeDTO,
+    T8ClientModel,
+    T8ClientModelDTO,
+    T8ClientProductConnectionsDTO,
+    T8ClientProductDTO,
+    T8ClientProjectConnectionsDTO,
+    T8ClientProjectDTO,
+    T8ClientUnitDTO,
+    T8EntityType,
+    T8GIMeshDescriptor,
+    T8GIMeshDescriptorDTO,
+    T8GIStyle,
+    T8GIStyleDTO,
+    T8GIRegion,
+    T8GIRegionDTO,
+    T8Product,
+    T8ProductWithGeometry,
+    T8Project,
+    T8Unit
+} from '@twinfinity/t8-client-model';
+import type { T8ProjectWithGeometry } 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,
+    AssetForbiddenError,
+    AssetConflictError,
+    AssetNotFoundError,
+    AssetAttachmentConflictError,
+    AssetAttachmentNotFoundError,
+    AssetBatchError,
+    TwinFileValidationError,
+    TwinFileConflictError,
+    TwinFileNotFoundError,
+    AssetCategoryValidationError,
+    AssetCategoryConflictError,
+    AssetCategoryNotFoundError,
+    AssetCategoryForbiddenError,
+    AssetTypeValidationError,
+    AssetTypeConflictError,
+    AssetTypeNotFoundError,
+    AssetTypeForbiddenError,
+    AssetCatalogTooLargeError,
+    isAssetCatalogTooLargeErrorBody,
+    TwinUnauthenticatedError,
+    readErrorBody
+} from './errors';
+import type {
+    AssetCategoryGet,
+    AssetCategoryPut,
+    AssetCatalogResponse,
+    AssetTypeGet,
+    AssetTypePut
+} from './types/asset-types-api';
+import type {
+    AttachmentGet,
+    AttachmentPost,
+    AssetAttachmentPut,
+    ApiCreateUploadSessionResponse,
+    UploadStatusGet
+} from './types/asset-attachment-api';
+import type { MyPermissions } from './types/twin-permissions-api';
+import { Twin } from './types/Twin';
+import { TwinGeometryInfo } from './types/TwinGeometryInfo';
+
+export interface ITwinClient {
+    /**
+     * @param relatedTo - Filter twins by container ID.
+     * @throws {TwinValidationError} On invalid query parameters (400).
+     */
+    listTwins(
+        relatedTo?: string,
+        page?: string,
+        limit?: number,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<ListTwinItem>>;
+
+    /**
+     * Fetches all twins by auto-paginating through {@link listTwins}. Caps at 1000 pages.
+     * @param relatedTo - Filter twins by container ID.
+     */
+    listAllTwins(relatedTo?: string, signal?: AbortSignal): Promise<ListTwinItem[]>;
+
+    /**
+     * @param twin - Twin ID string, or `{id, version}` to fetch a specific version.
+     * @throws {TwinNotFoundError} When the twin or version does not exist (404).
+     */
+    getTwin(twin: string | { id: string; version: number }, signal?: AbortSignal): Promise<TwinGet>;
+
+    /**
+     * @throws {TwinValidationError} On invalid query parameters (400).
+     */
+    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>;
+
+    /**
+     * Downloads and deserializes the T8 client model (t8cm + t8cm-ext) using default types.
+     * When no version is specified, searches versions newest-first for one containing t8cm content.
+     *
+     * @param twin - Twin ID string, or `{id, version}` to load a specific version.
+     * @throws {Error} When no version has t8cm content.
+     */
+    loadTwin(
+        twin: string | { id: string; version: number },
+        signal?: AbortSignal
+    ): Promise<Twin<T8Project, T8Product<T8EntityType>, T8EntityType, T8Unit>>;
+
+    /**
+     * Downloads and deserializes the T8 client model using custom factory functions for domain-specific types.
+     * When no version is specified, searches versions newest-first for one containing t8cm content.
+     *
+     * @param twin - Twin ID string, or `{id, version}` to load a specific version.
+     * @throws {Error} When no version has t8cm content.
+     */
+    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>>;
+
+    /**
+     * Downloads and deserializes geometry info (t8gi) using default types.
+     * When no version is specified, searches versions newest-first for one containing t8gi content.
+     *
+     * @param twin - Twin ID string, or `{id, version}` to load a specific version.
+     * @throws {Error} When no version has t8gi content.
+     */
+    loadGeometryInfo(
+        twin: string | { id: string; version: number },
+        signal?: AbortSignal
+    ): Promise<TwinGeometryInfo<T8GIMeshDescriptor, T8GIStyle, T8GIRegion>>;
+
+    /**
+     * Downloads and deserializes geometry info (t8gi) using custom factory functions.
+     * When no version is specified, searches versions newest-first for one containing t8gi content.
+     *
+     * @param twin - Twin ID string, or `{id, version}` to load a specific version.
+     * @throws {Error} When no version has t8gi content.
+     */
+    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>>;
+
+    /**
+     * Downloads and deserializes both the client model (t8cm) and geometry (t8gi/t8gd) into a combined result.
+     * When no version is specified, searches versions newest-first for one containing both t8cm and t8gi content.
+     *
+     * @param twin - Twin ID string, or `{id, version}` to load a specific version.
+     * @throws {Error} When no version has both t8cm and t8gi content.
+     */
+    loadTwinWithGeometry(
+        twin: string | { id: string; version: number },
+        signal?: AbortSignal
+    ): Promise<Twin<T8ProjectWithGeometry, T8ProductWithGeometry, T8EntityType, T8Unit>>;
+
+    /**
+     * Creates a new twin or updates an existing one (upsert). Provide `etag` in the twin body to update.
+     *
+     * @throws {TwinValidationError} On invalid request body (400).
+     * @throws {TwinConflictError} On etag mismatch (409). The error's `currentTwin` contains the server's current state.
+     */
+    createOrUpdateTwin(twinId: string, twin: TwinPut, signal?: AbortSignal): Promise<TwinGet>;
+
+    /** Alias for {@link createOrUpdateTwin}. */
+    updateTwin(twinId: string, twin: TwinPut, signal?: AbortSignal): Promise<TwinGet>;
+
+    /**
+     * @throws {TwinNotFoundError} When the twin does not exist (404).
+     * @throws {TwinConflictError} On etag mismatch (409). The error's `currentTwin` contains the server's current state.
+     */
+    restoreTwin(twinId: string, etag: string, signal?: AbortSignal): Promise<TwinGet>;
+
+    /**
+     * @throws {TwinNotFoundError} When the twin or version does not exist (404).
+     */
+    getTwinVersionContent(
+        twinId: string,
+        twinVersion: number,
+        signal?: AbortSignal
+    ): Promise<TwinVersionContentResponse>;
+
+    /**
+     * Returns content for the latest twin version.
+     * @throws {TwinNotFoundError} When the twin does not exist (404).
+     */
+    getTwinContent(twinId: string, signal?: AbortSignal): Promise<TwinVersionContentResponse>;
+
+    /** @throws {TwinNotFoundError} When the twin does not exist (404). */
+    getTwinDiagnostics(twinId: string, signal?: AbortSignal): Promise<TwinDiagnosticsResponse>;
+
+    /** @throws {TwinNotFoundError} When the twin or version does not exist (404). */
+    getTwinVersionDiagnostics(
+        twinId: string,
+        twinVersion: number,
+        signal?: AbortSignal
+    ): Promise<TwinDiagnosticsResponse>;
+
+    /**
+     * @throws {TwinValidationError} On invalid query parameters (400).
+     * @throws {TwinNotFoundError} When the twin or version does not exist (404).
+     */
+    getTwinVersionEvents(
+        twinId: string,
+        twinVersion: number,
+        offset?: number,
+        limit?: number,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<TwinProcessorEvent>>;
+
+    /**
+     * @throws {TwinValidationError} On invalid query parameters (400).
+     * @throws {ProcessorNotFoundError} When the processor does not exist for this twin version (404).
+     */
+    getProcessorEvents(
+        twinId: string,
+        twinVersion: number,
+        processorId: string,
+        offset?: number,
+        limit?: number,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<TwinProcessorEvent>>;
+
+    /**
+     * @throws {AssetValidationError} On invalid query parameters (400).
+     * @throws {AssetNotFoundError} When the twin does not exist (404).
+     */
+    listAssets(
+        twinId: string,
+        offset?: number,
+        limit?: number,
+        options?: { includeDeleted?: boolean },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<AssetListItem>>;
+
+    /** @throws {AssetNotFoundError} When the asset does not exist (404). */
+    getAsset(twinId: string, assetId: string, signal?: AbortSignal): Promise<AssetGet>;
+
+    /** @throws {AssetValidationError} On invalid request body (400). The error's `errorBody` has structured detail. */
+    createAssets(twinId: string, assets: AssetPost[], signal?: AbortSignal): Promise<AssetGet[]>;
+
+    /**
+     * @throws {AssetValidationError} On invalid request body (400). The error's `errorBody` has structured detail.
+     * @throws {AssetConflictError} On etag mismatch (409). The error's `currentAsset` contains the server's current state.
+     */
+    updateAsset(twinId: string, assetId: string, asset: AssetPut, signal?: AbortSignal): Promise<AssetGet>;
+
+    /**
+     * @throws {AssetNotFoundError} When the asset does not exist (404).
+     * @throws {AssetConflictError} On etag mismatch (409). The error's `currentAsset` contains the server's current state.
+     */
+    deleteAsset(twinId: string, assetId: string, etag: string, signal?: AbortSignal): Promise<AssetGet>;
+
+    /**
+     * @throws {AssetNotFoundError} When the asset does not exist (404).
+     * @throws {AssetConflictError} On etag mismatch (409). The error's `currentAsset` contains the server's current state.
+     */
+    restoreAsset(twinId: string, assetId: string, etag: string, signal?: AbortSignal): Promise<AssetGet>;
+
+    /**
+     * Executes a batch of asset operations (upsert, delete, restore) atomically.
+     * All operations succeed or all are rolled back.
+     *
+     * @param operations - Array of batch operations (max 1000).
+     * @throws {AssetValidationError} On validation failure (400).
+     * @throws {AssetForbiddenError} On insufficient permissions (403).
+     * @throws {AssetBatchError} On conflict (409) or not found (404). The error's `response` has per-item results with reverted statuses.
+     */
+    batchAssets(twinId: string, operations: AssetBatchOperation[], signal?: AbortSignal): Promise<AssetBatchResponse>;
+
+    /**
+     * Retrieves multiple assets by ID in a single request.
+     *
+     * @param ids - Array of asset IDs (max 1000).
+     * @throws {AssetValidationError} On validation failure (400).
+     */
+    batchGetAssets(twinId: string, ids: string[], signal?: AbortSignal): Promise<AssetBatchGetResponse>;
+
+    /** Lists attachments for a single asset. */
+    listAssetAttachments(
+        twinId: string,
+        assetId: string,
+        options?: { includeDeleted?: boolean; offset?: number; limit?: number; page?: string },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<AttachmentGet>>;
+
+    /**
+     * Downloads an attachment's blob as a `Response`. The caller decides
+     * whether to consume it as text, ArrayBuffer, or Blob.
+     * @throws {AssetAttachmentNotFoundError} When the attachment does not exist (404).
+     */
+    getAssetAttachmentBlob(
+        twinId: string,
+        assetId: string,
+        attachmentId: string,
+        signal?: AbortSignal
+    ): Promise<Response>;
+
+    /**
+     * Creates an upload session for a new attachment. The actual file bytes
+     * are uploaded out-of-band to {@link ApiCreateUploadSessionResponse.uploadUrl};
+     * use {@link uploadAssetAttachmentFile} for the canonical chunked-upload flow.
+     * The attachment row is materialized server-side when the blob lands.
+     * @throws {AssetAttachmentConflictError} When an attachment already exists
+     *  for the given id (409); retries must use a new attachmentId.
+     */
+    createAssetAttachmentUploadSession(
+        twinId: string,
+        assetId: string,
+        attachmentId: string,
+        body: AttachmentPost,
+        signal?: AbortSignal
+    ): Promise<ApiCreateUploadSessionResponse>;
+
+    /**
+     * Uploads a `File` / `Blob` to an existing upload session in one or more
+     * chunks, then resolves the upload token so the caller can poll
+     * {@link getAssetAttachmentUploadStatus}.
+     */
+    uploadAssetAttachmentFile(
+        session: ApiCreateUploadSessionResponse,
+        file: Blob,
+        signal?: AbortSignal
+    ): Promise<{ token: string }>;
+
+    /** Polls the in-memory upload-session cache for an attachment that's being uploaded. */
+    getAssetAttachmentUploadStatus(
+        twinId: string,
+        assetId: string,
+        token: string,
+        signal?: AbortSignal
+    ): Promise<UploadStatusGet>;
+
+    /**
+     * Updates an attachment's description / soft-delete flag. `documentId`
+     * is immutable — rebinding is rejected.
+     * @throws {AssetAttachmentConflictError} On etag mismatch (409). The
+     *  error's `currentAttachment` carries the server's current state.
+     * @throws {AssetAttachmentNotFoundError} When the attachment does not exist (404).
+     */
+    putAssetAttachment(
+        twinId: string,
+        assetId: string,
+        attachmentId: string,
+        body: AssetAttachmentPut,
+        signal?: AbortSignal
+    ): Promise<AttachmentGet>;
+
+    /**
+     * Soft-deletes an attachment.
+     * @throws {AssetAttachmentConflictError} On etag mismatch (409).
+     * @throws {AssetAttachmentNotFoundError} When the attachment does not exist (404).
+     */
+    deleteAssetAttachment(
+        twinId: string,
+        assetId: string,
+        attachmentId: string,
+        etag: string,
+        signal?: AbortSignal
+    ): Promise<AttachmentGet>;
+
+    /**
+     * Restores a soft-deleted attachment.
+     * @throws {AssetAttachmentConflictError} On etag mismatch (409).
+     * @throws {AssetAttachmentNotFoundError} When the attachment does not exist (404).
+     */
+    restoreAssetAttachment(
+        twinId: string,
+        assetId: string,
+        attachmentId: string,
+        etag: string,
+        signal?: AbortSignal
+    ): Promise<AttachmentGet>;
+
+    /**
+     * @throws {TwinNotFoundError} When the twin does not exist (404).
+     * @throws {TwinConflictError} On etag mismatch (409). The error's `currentTwin` contains the server's current state.
+     */
+    deleteTwin(twinId: string, etag: string, signal?: AbortSignal): Promise<TwinGet>;
+
+    /** @throws {TwinFileValidationError} On invalid query parameters (400). */
+    listTwinFiles(
+        twinId: string,
+        options?: TwinFileListOptions,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<TwinFileGet>>;
+
+    /**
+     * @throws {TwinFileNotFoundError} When the file does not exist (404).
+     * @throws {TwinFileValidationError} On invalid request (400).
+     */
+    getTwinFile(twinId: string, fileId: string, signal?: AbortSignal): Promise<TwinFileGet>;
+
+    /**
+     * @throws {TwinFileValidationError} On invalid request body (400).
+     * @throws {TwinFileConflictError} On etag mismatch (409). The error's `currentTwinFile` contains the server's current state.
+     */
+    createOrUpdateTwinFile(
+        twinId: string,
+        fileId: string,
+        twinFile: TwinFilePut,
+        signal?: AbortSignal
+    ): Promise<TwinFileGet>;
+
+    /**
+     * @throws {TwinFileNotFoundError} When the file does not exist (404).
+     * @throws {TwinFileConflictError} On etag mismatch (409). The error's `currentTwinFile` contains the server's current state.
+     * @throws {TwinFileValidationError} On invalid request (400).
+     */
+    deleteTwinFile(
+        twinId: string,
+        fileId: string,
+        deleteRequest: TwinFileDelete,
+        signal?: AbortSignal
+    ): Promise<TwinFileGet>;
+
+    /**
+     * @throws {TwinFileNotFoundError} When the file does not exist (404).
+     * @throws {TwinFileConflictError} On etag mismatch (409). The error's `currentTwinFile` contains the server's current state.
+     * @throws {TwinFileValidationError} On invalid request (400).
+     */
+    restoreTwinFile(twinId: string, fileId: string, etag: string, signal?: AbortSignal): Promise<TwinFileGet>;
+
+    /** @throws {TwinFileNotFoundError} When the file does not exist (404). */
+    getTwinFileContent(twinId: string, fileId: string, signal?: AbortSignal): Promise<Blob>;
+
+    /** @throws {TwinFileNotFoundError} When the file or version does not exist (404). */
+    getTwinFileVersion(twinId: string, fileId: string, version: number, signal?: AbortSignal): Promise<TwinFileGet>;
+
+    /** @throws {TwinFileValidationError} On invalid query parameters (400). */
+    listTwinFileVersions(
+        twinId: string,
+        fileId: string,
+        options?: TwinFileVersionListOptions,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<TwinFileGet>>;
+
+    /** @throws {TwinFileNotFoundError} When the file or version does not exist (404). */
+    getTwinFileVersionContent(twinId: string, fileId: string, version: number, signal?: AbortSignal): Promise<Blob>;
+
+    // ---------- Asset categories (TWINS-3643) ----------
+
+    /**
+     * Returns the caller's named, customer-scoped capabilities against the
+     * Twin service (e.g. `ViewAssetTypes`, `EditAssetTypes`). The admin app
+     * uses this to enable or disable buttons instead of letting the user
+     * click through to a 403.
+     *
+     * No client-side cache — every call hits the wire. Underlying scope
+     * grants don't shift within a session, so callers are expected to
+     * memoise the result themselves (e.g. via React Query / a once-on-mount
+     * fetch) rather than calling this on every render.
+     *
+     * Throws {@link TwinUnauthenticatedError} on 401 (no valid auth context;
+     * caller should redirect to login). Returns an empty `permissions` array
+     * on 403 (authenticated but no Twin-service capabilities). Unknown
+     * capability strings should be ignored — adding a new capability is a
+     * non-breaking change.
+     */
+    getMyPermissions(signal?: AbortSignal): Promise<MyPermissions>;
+
+    /**
+     * Returns the Twinfinity meta-schema document — the JSON Schema describing
+     * valid asset-type metadata schemas. The bytes the backend itself
+     * validates against, served verbatim. Power-user tools (Monaco-backed
+     * JSON editors, schema-aware tooling) fetch this at runtime so their
+     * in-editor diagnostics line up with what the server will accept,
+     * decoupled from the FE bundle's build time.
+     */
+    getAssetTypeMetaSchema(signal?: AbortSignal): Promise<Record<string, unknown>>;
+
+    /**
+     * @throws {AssetCategoryValidationError} On invalid query parameters (400).
+     */
+    listAssetCategories(
+        options?: { page?: string; limit?: number; includeDeleted?: boolean },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<AssetCategoryGet>>;
+
+    /** @throws {AssetCategoryNotFoundError} When the category does not exist (404). */
+    getAssetCategory(categoryId: string, signal?: AbortSignal): Promise<AssetCategoryGet>;
+
+    /**
+     * Upserts an asset category. Provide an empty/missing etag for first writes
+     * and the existing etag to update.
+     *
+     * @throws {AssetCategoryValidationError} On invalid request body (400).
+     * @throws {AssetCategoryConflictError} On etag mismatch (409). The error's `currentCategory` contains the server's current state.
+     */
+    putAssetCategory(categoryId: string, body: AssetCategoryPut, signal?: AbortSignal): Promise<AssetCategoryGet>;
+
+    /**
+     * Returns every version of a single asset category, newest first. Mirrors
+     * `listAssetTypeVersions` and `twin.get_twin_versions`.
+     *
+     * @throws {AssetCategoryNotFoundError} When the category's header row does not exist (404).
+     */
+    listAssetCategoryVersions(
+        categoryId: string,
+        options?: { page?: string; limit?: number; includeDeleted?: boolean },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<AssetCategoryGet>>;
+
+    /**
+     * Soft-deletes a category. Inserts a new asset_category_versions row with
+     * `is_deleted=true`; the previous version is retained as an audit trail.
+     *
+     * @throws {AssetCategoryNotFoundError} When the category does not exist (404).
+     * @throws {AssetCategoryConflictError} On etag mismatch (409).
+     */
+    deleteAssetCategory(categoryId: string, etag: string, signal?: AbortSignal): Promise<AssetCategoryGet>;
+
+    /**
+     * Restores a soft-deleted category. Inserts a new asset_category_versions
+     * row with `is_deleted=false`; mirrors twin restore.
+     *
+     * @throws {AssetCategoryNotFoundError} When the category does not exist (404).
+     * @throws {AssetCategoryConflictError} On etag mismatch (409).
+     */
+    restoreAssetCategory(categoryId: string, etag: string, signal?: AbortSignal): Promise<AssetCategoryGet>;
+
+    // ---------- Asset types (TWINS-3643) ----------
+
+    /** @throws {AssetTypeValidationError} On invalid query parameters (400). */
+    listAssetTypes(
+        categoryId: string,
+        options?: { page?: string; limit?: number; includeDeleted?: boolean },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<AssetTypeGet>>;
+
+    /** @throws {AssetTypeNotFoundError} When the category or type does not exist (404). */
+    getAssetType(categoryId: string, typeId: string, signal?: AbortSignal): Promise<AssetTypeGet>;
+
+    /**
+     * Returns every version of a single asset type, newest first. Mirrors
+     * `twin.get_twin_versions`.
+     *
+     * @throws {AssetTypeNotFoundError} When the type's header row does not exist (404).
+     */
+    listAssetTypeVersions(
+        categoryId: string,
+        typeId: string,
+        options?: { page?: string; limit?: number; includeDeleted?: boolean },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<AssetTypeGet>>;
+
+    /**
+     * Upserts an asset type. The metadata schema is validated against the
+     * Twinfinity meta-schema at the API boundary; invalid schemas surface as
+     * a 400 with `cause: MetadataSchemaInvalid`.
+     *
+     * @throws {AssetTypeValidationError} On invalid request body (400). The error's `errorBody` carries the structured cause.
+     * @throws {AssetTypeConflictError} On etag mismatch (409). The error's `currentType` contains the server's current state.
+     */
+    putAssetType(categoryId: string, typeId: string, body: AssetTypePut, signal?: AbortSignal): Promise<AssetTypeGet>;
+
+    /**
+     * Soft-deletes a type. Inserts a new asset_type_versions row with
+     * `is_deleted=true`; the previous version is retained as an audit trail.
+     *
+     * @throws {AssetTypeNotFoundError} When the type does not exist (404).
+     * @throws {AssetTypeConflictError} On etag mismatch (409).
+     */
+    deleteAssetType(categoryId: string, typeId: string, etag: string, signal?: AbortSignal): Promise<AssetTypeGet>;
+
+    /**
+     * Restores a soft-deleted type. Inserts a new asset_type_versions row with
+     * `is_deleted=false`; mirrors twin restore.
+     *
+     * @throws {AssetTypeNotFoundError} When the type does not exist (404).
+     * @throws {AssetTypeConflictError} On etag mismatch (409).
+     */
+    restoreAssetType(categoryId: string, typeId: string, etag: string, signal?: AbortSignal): Promise<AssetTypeGet>;
+
+    /**
+     * Returns the customer's asset-type catalog: categories nested with
+     * their latest non-deleted types and full metadata schemas inline. One
+     * round-trip is enough to populate a picker dropdown and render any
+     * per-type metadata form.
+     */
+    getAssetTypeCatalog(signal?: AbortSignal): Promise<AssetCatalogResponse>;
+}
+
+export class TwinClient implements ITwinClient {
+    private readonly _baseUrl: string;
+    private readonly _assetTypeCatalogUrl: string;
+
+    constructor(
+        baseUrl: string | URL,
+        private readonly _httpClient: TwinfinityHttpClient
+    ) {
+        const base = String(baseUrl).replace(/\/+$/, '');
+        this._baseUrl = `${base}/_ps/twins`;
+        this._assetTypeCatalogUrl = `${base}/_ps/asset-type-catalog`;
+    }
+
+    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: { Accept: 'application/json' },
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as PaginatedResponse<ListTwinItem>;
+        }
+
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            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: { Accept: '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: { Accept: 'application/json' },
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as PaginatedResponse<ListTwinItem>;
+        }
+
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            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`);
+    }
+
+    private async loadTwinWithGeometryVersion(
+        twinId: string,
+        twinVersion: number,
+        signal?: AbortSignal
+    ): Promise<T8ClientModel<T8ProjectWithGeometry, T8ProductWithGeometry, T8EntityType, T8Unit> | undefined> {
+        const twinContent = await this.getTwinVersionContent(twinId, twinVersion, signal);
+
+        const t8cmItem = twinContent.content.find((item) => item.format === 't8cm');
+        const t8giItem = twinContent.content.find((item) => item.format === 't8gi');
+
+        if (t8cmItem === undefined || t8giItem === undefined) {
+            return undefined;
+        }
+
+        const t8cmExtensions = twinContent.content.filter((item) => item.format === 't8cm-ext');
+        const t8gdItem = twinContent.content.find((item) => item.format === 't8gd');
+
+        const downloads = [
+            this.downloadTwinContent(twinId, twinVersion, t8cmItem, signal),
+            ...t8cmExtensions.map((ext) => this.downloadTwinContent(twinId, twinVersion, ext, signal)),
+            this.downloadTwinContent(twinId, twinVersion, t8giItem, signal),
+            ...(t8gdItem ? [this.downloadTwinContent(twinId, twinVersion, t8gdItem, signal)] : [])
+        ];
+
+        const allData = await Promise.all(downloads);
+
+        const t8cmCount = 1 + t8cmExtensions.length;
+        const t8cmData = allData.slice(0, t8cmCount);
+        const t8giData = allData[t8cmCount];
+        const t8gdData = t8gdItem ? allData[t8cmCount + 1] : undefined;
+
+        return readT8ClientModelWithGeometry(t8cmData, t8giData, t8gdData);
+    }
+
+    async loadTwinWithGeometry(
+        twin: string | { id: string; version: number },
+        signal?: AbortSignal
+    ): Promise<Twin<T8ProjectWithGeometry, T8ProductWithGeometry, T8EntityType, T8Unit>> {
+        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.loadTwinWithGeometryVersion(twinId, specifiedVersion, 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.loadTwinWithGeometryVersion(twinId, versionItem.version, signal);
+                if (model !== undefined) {
+                    return {
+                        id: twinId,
+                        version: versionItem.version,
+                        model
+                    };
+                }
+            }
+            page = versions.pagination.nextPage;
+        }
+
+        throw new Error(`Twin ${twinId} does not have a client model with geometry`);
+    }
+
+    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 readErrorBody(response);
+            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: { Accept: '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: { Accept: '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: { Accept: '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: { Accept: '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: { Accept: 'application/json' },
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as PaginatedResponse<TwinProcessorEvent>;
+        }
+
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            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: { Accept: 'application/json' },
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as PaginatedResponse<TwinProcessorEvent>;
+        }
+
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            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: { Accept: 'application/json' },
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as PaginatedResponse<AssetListItem>;
+        }
+
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            throw new AssetValidationError(`Asset listing validation failed: ${errorBody.detail}`, errorBody);
+        }
+
+        if (response.status === 404) {
+            throw new AssetNotFoundError(`Twin ${twinId} not found`);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to list assets: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async getAsset(twinId: string, assetId: string, signal?: AbortSignal): Promise<AssetGet> {
+        const response = await this._httpClient.fetch(HttpMethod.Get, `${this._baseUrl}/${twinId}/assets/${assetId}`, {
+            headers: { Accept: '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 errorBody = await readErrorBody(response);
+            throw new AssetValidationError(`Asset validation failed: ${errorBody.detail}`, errorBody);
+        }
+
+        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 errorBody = await readErrorBody(response);
+            throw new AssetValidationError(`Asset validation failed: ${errorBody.detail}`, errorBody);
+        }
+
+        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}`);
+    }
+
+    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}`);
+    }
+
+    async batchAssets(
+        twinId: string,
+        operations: AssetBatchOperation[],
+        signal?: AbortSignal
+    ): Promise<AssetBatchResponse> {
+        const response = await this._httpClient.fetch(HttpMethod.Post, `${this._baseUrl}/${twinId}/assets/batch`, {
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ operations }),
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as AssetBatchResponse;
+        }
+
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            throw new AssetValidationError(`Asset batch validation failed: ${errorBody.detail}`, errorBody);
+        }
+
+        if (response.status === 403) {
+            const errorText = await response.text();
+            throw new AssetForbiddenError(`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}`);
+    }
+
+    async batchGetAssets(twinId: string, ids: string[], signal?: AbortSignal): 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 }),
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as AssetBatchGetResponse;
+        }
+
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            throw new AssetValidationError(`Asset batch-get validation failed: ${errorBody.detail}`, errorBody);
+        }
+
+        const errorText = await response.text();
+        throw new Error(`Failed to batch-get assets: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    // ────────── Asset attachments ──────────
+
+    async listAssetAttachments(
+        twinId: string,
+        assetId: string,
+        options?: { includeDeleted?: boolean; offset?: number; limit?: number; page?: string },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<AttachmentGet>> {
+        const params = new URLSearchParams();
+        if (options?.includeDeleted) params.set('includeDeleted', 'true');
+        if (options?.offset !== undefined) params.set('offset', String(options.offset));
+        if (options?.limit !== undefined) params.set('limit', String(options.limit));
+        if (options?.page) params.set('page', options.page);
+
+        const url = `${this._baseUrl}/${twinId}/assets/${assetId}/attachments${params.toString() ? `?${params}` : ''}`;
+        const response = await this._httpClient.fetch(HttpMethod.Get, url, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+
+        if (response.ok) return (await response.json()) as PaginatedResponse<AttachmentGet>;
+        if (response.status === 404) throw new AssetNotFoundError(`Asset ${assetId} not found`);
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            throw new AssetValidationError(`Attachment listing failed: ${errorBody.detail}`, errorBody);
+        }
+        const errorText = await response.text();
+        throw new Error(`Failed to list attachments: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async getAssetAttachmentBlob(
+        twinId: string,
+        assetId: string,
+        attachmentId: string,
+        signal?: AbortSignal
+    ): Promise<Response> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Get,
+            `${this._baseUrl}/${twinId}/assets/${assetId}/attachments/${attachmentId}`,
+            { signal }
+        );
+        if (response.ok) return response;
+        if (response.status === 404) throw new AssetAttachmentNotFoundError(`Attachment ${attachmentId} not found`);
+        const errorText = await response.text();
+        throw new Error(`Failed to fetch attachment blob: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async createAssetAttachmentUploadSession(
+        twinId: string,
+        assetId: string,
+        attachmentId: string,
+        body: AttachmentPost,
+        signal?: AbortSignal
+    ): Promise<ApiCreateUploadSessionResponse> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Post,
+            `${this._baseUrl}/${twinId}/assets/${assetId}/attachments/${attachmentId}/createAttachmentUploadSession`,
+            {
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+                signal
+            }
+        );
+        if (response.ok) return (await response.json()) as ApiCreateUploadSessionResponse;
+        if (response.status === 409) {
+            const conflicted = (await response.json()) as AttachmentGet;
+            throw new AssetAttachmentConflictError(
+                `Attachment ${attachmentId} already exists; pick a new id for retries`,
+                conflicted
+            );
+        }
+        if (response.status === 404) throw new AssetNotFoundError(`Asset ${assetId} not found`);
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            throw new AssetValidationError(`Upload session creation failed: ${errorBody.detail}`, errorBody);
+        }
+        const errorText = await response.text();
+        throw new Error(`Failed to create upload session: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async uploadAssetAttachmentFile(
+        session: ApiCreateUploadSessionResponse,
+        file: Blob,
+        signal?: AbortSignal
+    ): Promise<{ token: string }> {
+        // The token is encoded as a query param on the upload URL; we lift it
+        // out for the caller so they can poll uploadStatus without re-parsing.
+        const tokenMatch = session.uploadUrl.match(/token=([^&]+)/);
+        if (!tokenMatch) {
+            throw new Error(`Upload session URL is missing a token query parameter: ${session.uploadUrl}`);
+        }
+        const token = tokenMatch[1];
+
+        const chunkSize = Math.max(1, session.maxChunkSize || file.size);
+        const total = file.size;
+        let offset = 0;
+
+        // Even an empty file needs at least one PUT so the upload session
+        // gets a finalize signal. uploadChunks() in the integration tests
+        // unconditionally PUTs at least one chunk too.
+        do {
+            const end = Math.min(offset + chunkSize, total);
+            const chunk = file.slice(offset, end);
+            const lastByte = Math.max(0, end - 1);
+            const response = await this._httpClient.fetch(HttpMethod.Put, session.uploadUrl, {
+                headers: { 'Content-Range': `bytes ${offset}-${lastByte}/${total}` },
+                body: chunk,
+                signal
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(
+                    `Upload chunk failed at offset ${offset}: ${response.status} ${response.statusText} - ${errorText}`
+                );
+            }
+            offset = end;
+        } while (offset < total);
+
+        return { token };
+    }
+
+    async getAssetAttachmentUploadStatus(
+        twinId: string,
+        assetId: string,
+        token: string,
+        signal?: AbortSignal
+    ): Promise<UploadStatusGet> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Get,
+            `${this._baseUrl}/${twinId}/assets/${assetId}/attachments/uploadStatus/${encodeURIComponent(token)}`,
+            { headers: { Accept: 'application/json' }, signal }
+        );
+        if (response.ok) return (await response.json()) as UploadStatusGet;
+        if (response.status === 404) return { status: 'NotFound' };
+        const errorText = await response.text();
+        throw new Error(`Failed to get upload status: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async putAssetAttachment(
+        twinId: string,
+        assetId: string,
+        attachmentId: string,
+        body: AssetAttachmentPut,
+        signal?: AbortSignal
+    ): Promise<AttachmentGet> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Put,
+            `${this._baseUrl}/${twinId}/assets/${assetId}/attachments/${attachmentId}`,
+            {
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+                signal
+            }
+        );
+        if (response.ok) return (await response.json()) as AttachmentGet;
+        if (response.status === 409) {
+            const conflicted = (await response.json()) as AttachmentGet;
+            throw new AssetAttachmentConflictError('Attachment has been modified by another user', conflicted);
+        }
+        if (response.status === 404) throw new AssetAttachmentNotFoundError(`Attachment ${attachmentId} not found`);
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            throw new AssetValidationError(`Attachment update failed: ${errorBody.detail}`, errorBody);
+        }
+        const errorText = await response.text();
+        throw new Error(`Failed to update attachment: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async deleteAssetAttachment(
+        twinId: string,
+        assetId: string,
+        attachmentId: string,
+        etag: string,
+        signal?: AbortSignal
+    ): Promise<AttachmentGet> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Delete,
+            `${this._baseUrl}/${twinId}/assets/${assetId}/attachments/${attachmentId}`,
+            {
+                headers: { 'If-Match': etag },
+                signal
+            }
+        );
+        if (response.ok) return (await response.json()) as AttachmentGet;
+        if (response.status === 409) {
+            const conflicted = (await response.json()) as AttachmentGet;
+            throw new AssetAttachmentConflictError('Attachment has been modified by another user', conflicted);
+        }
+        if (response.status === 404) throw new AssetAttachmentNotFoundError(`Attachment ${attachmentId} not found`);
+        const errorText = await response.text();
+        throw new Error(`Failed to delete attachment: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async restoreAssetAttachment(
+        twinId: string,
+        assetId: string,
+        attachmentId: string,
+        etag: string,
+        signal?: AbortSignal
+    ): Promise<AttachmentGet> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Put,
+            `${this._baseUrl}/${twinId}/assets/${assetId}/attachments/${attachmentId}/restore`,
+            {
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ etag }),
+                signal
+            }
+        );
+        if (response.ok) return (await response.json()) as AttachmentGet;
+        if (response.status === 409) {
+            const conflicted = (await response.json()) as AttachmentGet;
+            throw new AssetAttachmentConflictError('Attachment has been modified by another user', conflicted);
+        }
+        if (response.status === 404) throw new AssetAttachmentNotFoundError(`Attachment ${attachmentId} not found`);
+        const errorText = await response.text();
+        throw new Error(`Failed to restore attachment: ${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: { Accept: 'application/json' },
+            signal
+        });
+
+        if (response.ok) {
+            return (await response.json()) as PaginatedResponse<TwinFileGet>;
+        }
+
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            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: { Accept: '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 readErrorBody(response);
+            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 readErrorBody(response);
+            throw new TwinFileValidationError(
+                `Twin file version listing validation failed: ${errorBody.detail}`,
+                errorBody
+            );
+        }
+
+        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
+        });
+    }
+
+    // ---------- Asset categories ----------
+
+    async getMyPermissions(signal?: AbortSignal): Promise<MyPermissions> {
+        const url = `${this._baseUrl}/permissions/me`;
+        const response = await this._httpClient.fetch(HttpMethod.Get, url, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+        if (response.ok) {
+            return (await response.json()) as MyPermissions;
+        }
+        // 401: no valid auth context. Throw so consumers can redirect to
+        // login / refresh tokens rather than mistake an expired session for
+        // "logged-in user with no grants."
+        if (response.status === 401) {
+            throw new TwinUnauthenticatedError('Not authenticated');
+        }
+        // 403: authenticated but no Twin-service capabilities. Surface as an
+        // empty array so consumers can treat it like a logged-in user with
+        // zero grants.
+        if (response.status === 403) {
+            return { permissions: [] };
+        }
+        throw new Error(`Failed to fetch permissions: ${response.status} ${response.statusText}`);
+    }
+
+    async getAssetTypeMetaSchema(signal?: AbortSignal): Promise<Record<string, unknown>> {
+        const url = `${this._assetTypeCatalogUrl}/meta-schema`;
+        const response = await this._httpClient.fetch(HttpMethod.Get, url, {
+            headers: { Accept: 'application/schema+json, application/json' },
+            signal
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch meta-schema: ${response.status} ${response.statusText}`);
+        }
+        return (await response.json()) as Record<string, unknown>;
+    }
+
+    async listAssetCategories(
+        options?: { page?: string; limit?: number; includeDeleted?: boolean },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<AssetCategoryGet>> {
+        const params = new URLSearchParams();
+        if (options?.page !== undefined) params.set('page', options.page);
+        if (options?.limit !== undefined) params.set('limit', options.limit.toString());
+        if (options?.includeDeleted) params.set('includeDeleted', 'true');
+
+        const url = params.toString()
+            ? `${this._assetTypeCatalogUrl}/categories?${params}`
+            : `${this._assetTypeCatalogUrl}/categories`;
+        const response = await this._httpClient.fetch(HttpMethod.Get, url, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+
+        if (response.ok) return (await response.json()) as PaginatedResponse<AssetCategoryGet>;
+        if (response.status === 403) throw new AssetCategoryForbiddenError('Asset category listing forbidden');
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            throw new AssetCategoryValidationError(`Asset category listing failed: ${errorBody.detail}`, errorBody);
+        }
+        throw new Error(`Failed to list asset categories: ${response.status} ${response.statusText}`);
+    }
+
+    async getAssetCategory(categoryId: string, signal?: AbortSignal): Promise<AssetCategoryGet> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Get,
+            `${this._assetTypeCatalogUrl}/categories/${categoryId}`,
+            {
+                headers: { Accept: 'application/json' },
+                signal
+            }
+        );
+        if (response.ok) return (await response.json()) as AssetCategoryGet;
+        if (response.status === 403)
+            throw new AssetCategoryForbiddenError(`Asset category ${categoryId} read forbidden`);
+        if (response.status === 404) throw new AssetCategoryNotFoundError(`Asset category ${categoryId} not found`);
+        throw new Error(`Failed to get asset category: ${response.status} ${response.statusText}`);
+    }
+
+    async putAssetCategory(
+        categoryId: string,
+        body: AssetCategoryPut,
+        signal?: AbortSignal
+    ): Promise<AssetCategoryGet> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Put,
+            `${this._assetTypeCatalogUrl}/categories/${categoryId}`,
+            {
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+                signal
+            }
+        );
+        if (response.ok) return (await response.json()) as AssetCategoryGet;
+        if (response.status === 403) throw new AssetCategoryForbiddenError('Asset category upsert forbidden');
+        if (response.status === 409) {
+            const current = (await response.json()) as AssetCategoryGet;
+            throw new AssetCategoryConflictError('Asset category was modified by another user', current);
+        }
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            throw new AssetCategoryValidationError(`Asset category validation failed: ${errorBody.detail}`, errorBody);
+        }
+        const errorText = await response.text();
+        throw new Error(`Failed to upsert asset category: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async deleteAssetCategory(categoryId: string, etag: string, signal?: AbortSignal): Promise<AssetCategoryGet> {
+        return this._categoryDeleteOrRestore(categoryId, etag, /*isRestore*/ false, signal);
+    }
+
+    async restoreAssetCategory(categoryId: string, etag: string, signal?: AbortSignal): Promise<AssetCategoryGet> {
+        return this._categoryDeleteOrRestore(categoryId, etag, /*isRestore*/ true, signal);
+    }
+
+    private async _categoryDeleteOrRestore(
+        categoryId: string,
+        etag: string,
+        isRestore: boolean,
+        signal?: AbortSignal
+    ): Promise<AssetCategoryGet> {
+        const url = isRestore
+            ? `${this._assetTypeCatalogUrl}/categories/${categoryId}/restore`
+            : `${this._assetTypeCatalogUrl}/categories/${categoryId}`;
+        const method = isRestore ? HttpMethod.Put : HttpMethod.Delete;
+        const response = await this._httpClient.fetch(method, url, {
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ etag }),
+            signal
+        });
+        if (response.ok) return (await response.json()) as AssetCategoryGet;
+        if (response.status === 403) {
+            const op = isRestore ? 'restore' : 'delete';
+            throw new AssetCategoryForbiddenError(`Asset category ${op} forbidden`);
+        }
+        if (response.status === 409) {
+            const current = (await response.json()) as AssetCategoryGet;
+            throw new AssetCategoryConflictError('Asset category was modified by another user', current);
+        }
+        if (response.status === 404) throw new AssetCategoryNotFoundError(`Asset category ${categoryId} not found`);
+        const errorText = await response.text();
+        const op = isRestore ? 'restore' : 'delete';
+        throw new Error(`Failed to ${op} asset category: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async listAssetCategoryVersions(
+        categoryId: string,
+        options?: { page?: string; limit?: number; includeDeleted?: boolean },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<AssetCategoryGet>> {
+        const params = new URLSearchParams();
+        if (options?.page !== undefined) params.set('page', options.page);
+        if (options?.limit !== undefined) params.set('limit', options.limit.toString());
+        if (options?.includeDeleted) params.set('includeDeleted', 'true');
+
+        const baseUrl = `${this._assetTypeCatalogUrl}/categories/${categoryId}/versions`;
+        const url = params.toString() ? `${baseUrl}?${params}` : baseUrl;
+        const response = await this._httpClient.fetch(HttpMethod.Get, url, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+
+        if (response.ok) return (await response.json()) as PaginatedResponse<AssetCategoryGet>;
+        if (response.status === 403) throw new AssetCategoryForbiddenError('Asset category version listing forbidden');
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            throw new AssetCategoryValidationError(
+                `Asset category version listing failed: ${errorBody.detail}`,
+                errorBody
+            );
+        }
+        if (response.status === 404) throw new AssetCategoryNotFoundError(`Asset category ${categoryId} not found`);
+        throw new Error(`Failed to list asset category versions: ${response.status} ${response.statusText}`);
+    }
+
+    // ---------- Asset types ----------
+
+    async listAssetTypes(
+        categoryId: string,
+        options?: { page?: string; limit?: number; includeDeleted?: boolean },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<AssetTypeGet>> {
+        const params = new URLSearchParams();
+        if (options?.page !== undefined) params.set('page', options.page);
+        if (options?.limit !== undefined) params.set('limit', options.limit.toString());
+        if (options?.includeDeleted) params.set('includeDeleted', 'true');
+
+        const baseUrl = `${this._assetTypeCatalogUrl}/categories/${categoryId}/types`;
+        const url = params.toString() ? `${baseUrl}?${params}` : baseUrl;
+        const response = await this._httpClient.fetch(HttpMethod.Get, url, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+
+        if (response.ok) return (await response.json()) as PaginatedResponse<AssetTypeGet>;
+        if (response.status === 403) throw new AssetTypeForbiddenError('Asset type listing forbidden');
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            throw new AssetTypeValidationError(`Asset type listing failed: ${errorBody.detail}`, errorBody);
+        }
+        throw new Error(`Failed to list asset types: ${response.status} ${response.statusText}`);
+    }
+
+    async getAssetType(categoryId: string, typeId: string, signal?: AbortSignal): Promise<AssetTypeGet> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Get,
+            `${this._assetTypeCatalogUrl}/categories/${categoryId}/types/${typeId}`,
+            { headers: { Accept: 'application/json' }, signal }
+        );
+        if (response.ok) return (await response.json()) as AssetTypeGet;
+        if (response.status === 403) throw new AssetTypeForbiddenError(`Asset type ${typeId} read forbidden`);
+        if (response.status === 404) throw new AssetTypeNotFoundError(`Asset type ${typeId} not found`);
+        throw new Error(`Failed to get asset type: ${response.status} ${response.statusText}`);
+    }
+
+    async listAssetTypeVersions(
+        categoryId: string,
+        typeId: string,
+        options?: { page?: string; limit?: number; includeDeleted?: boolean },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<AssetTypeGet>> {
+        const params = new URLSearchParams();
+        if (options?.page !== undefined) params.set('page', options.page);
+        if (options?.limit !== undefined) params.set('limit', options.limit.toString());
+        if (options?.includeDeleted) params.set('includeDeleted', 'true');
+
+        const baseUrl = `${this._assetTypeCatalogUrl}/categories/${categoryId}/types/${typeId}/versions`;
+        const url = params.toString() ? `${baseUrl}?${params}` : baseUrl;
+        const response = await this._httpClient.fetch(HttpMethod.Get, url, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+
+        if (response.ok) return (await response.json()) as PaginatedResponse<AssetTypeGet>;
+        if (response.status === 403) throw new AssetTypeForbiddenError('Asset type version listing forbidden');
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            throw new AssetTypeValidationError(`Asset type version listing failed: ${errorBody.detail}`, errorBody);
+        }
+        if (response.status === 404) throw new AssetTypeNotFoundError(`Asset type ${typeId} not found`);
+        throw new Error(`Failed to list asset type versions: ${response.status} ${response.statusText}`);
+    }
+
+    async putAssetType(
+        categoryId: string,
+        typeId: string,
+        body: AssetTypePut,
+        signal?: AbortSignal
+    ): Promise<AssetTypeGet> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Put,
+            `${this._assetTypeCatalogUrl}/categories/${categoryId}/types/${typeId}`,
+            {
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+                signal
+            }
+        );
+        if (response.ok) return (await response.json()) as AssetTypeGet;
+        if (response.status === 403) throw new AssetTypeForbiddenError('Asset type upsert forbidden');
+        if (response.status === 409) {
+            const current = (await response.json()) as AssetTypeGet;
+            throw new AssetTypeConflictError('Asset type was modified by another user', current);
+        }
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            throw new AssetTypeValidationError(`Asset type validation failed: ${errorBody.detail}`, errorBody);
+        }
+        const errorText = await response.text();
+        throw new Error(`Failed to upsert asset type: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async deleteAssetType(
+        categoryId: string,
+        typeId: string,
+        etag: string,
+        signal?: AbortSignal
+    ): Promise<AssetTypeGet> {
+        return this._typeDeleteOrRestore(categoryId, typeId, etag, /*isRestore*/ false, signal);
+    }
+
+    async restoreAssetType(
+        categoryId: string,
+        typeId: string,
+        etag: string,
+        signal?: AbortSignal
+    ): Promise<AssetTypeGet> {
+        return this._typeDeleteOrRestore(categoryId, typeId, etag, /*isRestore*/ true, signal);
+    }
+
+    private async _typeDeleteOrRestore(
+        categoryId: string,
+        typeId: string,
+        etag: string,
+        isRestore: boolean,
+        signal?: AbortSignal
+    ): Promise<AssetTypeGet> {
+        const url = isRestore
+            ? `${this._assetTypeCatalogUrl}/categories/${categoryId}/types/${typeId}/restore`
+            : `${this._assetTypeCatalogUrl}/categories/${categoryId}/types/${typeId}`;
+        const method = isRestore ? HttpMethod.Put : HttpMethod.Delete;
+        const response = await this._httpClient.fetch(method, url, {
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ etag }),
+            signal
+        });
+        if (response.ok) return (await response.json()) as AssetTypeGet;
+        if (response.status === 403) {
+            const op = isRestore ? 'restore' : 'delete';
+            throw new AssetTypeForbiddenError(`Asset type ${op} forbidden`);
+        }
+        if (response.status === 409) {
+            const current = (await response.json()) as AssetTypeGet;
+            throw new AssetTypeConflictError('Asset type was modified by another user', current);
+        }
+        if (response.status === 404) throw new AssetTypeNotFoundError(`Asset type ${typeId} not found`);
+        const errorText = await response.text();
+        const op = isRestore ? 'restore' : 'delete';
+        throw new Error(`Failed to ${op} asset type: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    async getAssetTypeCatalog(signal?: AbortSignal): Promise<AssetCatalogResponse> {
+        const response = await this._httpClient.fetch(HttpMethod.Get, this._assetTypeCatalogUrl, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+        if (response.ok) return (await response.json()) as AssetCatalogResponse;
+        if (response.status === 403) throw new AssetCategoryForbiddenError('Asset type catalog read forbidden');
+        if (response.status === 400) {
+            // The server emits a single structured 400 here today —
+            // `cause: 'CatalogTooLarge'` — to flag a tenant whose catalog
+            // overflows the per-customer cap. Surface as a typed error so
+            // picker UIs can render "use search" instead of crashing on
+            // missing rows. Any other 400 (malformed CatalogTooLarge body,
+            // future cause) falls through to the generic error below so the
+            // caller still sees the raw response.
+            const errorBody = await readErrorBody(response);
+            if (isAssetCatalogTooLargeErrorBody(errorBody)) {
+                throw new AssetCatalogTooLargeError(`Asset type catalog too large: ${errorBody.detail}`, errorBody);
+            }
+            throw new Error(
+                `Failed to get asset-type catalog: ${response.status} ${response.statusText} - ${errorBody.detail}`
+            );
+        }
+        const errorText = await response.text();
+        throw new Error(`Failed to get asset-type catalog: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+}