@twinfinity/twin 0.0.0-feature.31596

package/src/TwinClient.ts

@@ -0,0 +1,3113 @@
+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,
+    TwinPermissionsConflictError,
+    TwinPermissionsForbiddenError,
+    TwinPrincipalNotFoundError,
+    TwinTemporarilyUnavailableError,
+    AssetPermissionsConflictError,
+    readErrorBody
+} from './errors';
+import type { TwinPermissionsConflictErrorBody, AssetPermissionsConflictErrorBody } 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,
+    MyTwinPermissions,
+    TwinGroupGet,
+    TwinGroupsGet,
+    TwinPermissionsPut,
+    TwinPrincipalPermissionsGet,
+    AssetGroupGet,
+    AssetGroupsGet,
+    AssetPermissionsPut,
+    AssetPrincipalPermissionsGet
+} from './types/twin-permissions-api';
+import { Twin } from './types/Twin';
+import { TwinGeometryInfo } from './types/TwinGeometryInfo';
+
+export interface ITwinClient {
+    /**
+     * Rooted twins base URL — typically `<host>/sites/<container>/_ps/twins`.
+     * Use this when constructing related URLs (e.g. twin content) that need
+     * to live in the same auth scope as the metadata calls.
+     */
+    readonly baseUrl: string;
+
+    /**
+     * @param options - `relatedTo` filters by container ID; `includeDeleted` includes soft-deleted twins
+     * (returned redacted, default false); `page`/`limit` control pagination.
+     * @throws {TwinValidationError} On invalid query parameters (400).
+     */
+    listTwins(
+        options?: {
+            relatedTo?: string;
+            includeDeleted?: boolean;
+            page?: string;
+            limit?: number;
+        },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<ListTwinItem>>;
+    /**
+     * @deprecated Use the options-object form: `listTwins({ relatedTo, page, limit }, signal)`.
+     * The positional form has no `includeDeleted` parameter; that is only reachable via the options object.
+     */
+    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 options - `relatedTo` filters by container ID; `includeDeleted` includes soft-deleted twins
+     * (returned redacted, default false).
+     */
+    listAllTwins(
+        options?: { relatedTo?: string; includeDeleted?: boolean },
+        signal?: AbortSignal
+    ): Promise<ListTwinItem[]>;
+    /**
+     * @deprecated Use the options-object form: `listAllTwins({ relatedTo }, signal)`.
+     * The positional form has no `includeDeleted` parameter; that is only reachable via the options object.
+     */
+    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 {AssetBatchError} When the batch rolled back. The error's `response` has per-item
+     * results with reverted statuses, and is thrown for any status the failing item carried --
+     * 400, 404 or 409.
+     * @throws {AssetValidationError} When the whole request was rejected before any item ran (400):
+     * an empty batch, duplicate ids, a body/URL twin mismatch, oversized metadata.
+     * @throws {AssetForbiddenError} On insufficient permissions (403).
+     */
+    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 — the asset-domain vocabulary `ViewAssets`, `EditAssets`,
+     * `DeleteAssets`, `EditAssetTypes` and `ManageAssetPermissions`.
+     * 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.
+     *
+     * A 503 throws rather than answering with an empty array: the Permission
+     * service gave no answer, so the capabilities are unknown rather than
+     * absent, and the call is safe to retry unchanged.
+     */
+    getMyPermissions(signal?: AbortSignal): Promise<MyPermissions>;
+
+    // ---------- Twin-scoped permissions (TWINS-2982) ----------
+
+    /**
+     * Returns the capabilities the caller holds on one specific twin. Open to every
+     * authenticated caller — an empty list is an honest answer rather than a refusal —
+     * so a UI can gate its controls on this before it knows anything about the caller.
+     *
+     * The answer mixes vocabularies: the twin's own `TwinScopedCapability` values, plus the
+     * asset-instance capabilities `ViewAssets`, `EditAssets` and `DeleteAssets`, which gate the
+     * assets hanging off this twin. The catalog capabilities and `ManageAssetPermissions` are not
+     * twin-bound and are absent here.
+     *
+     * Distinct from {@link getMyPermissions}, which answers the customer-scoped question over the
+     * whole asset domain. That one returns an empty list on 403; this route has no capability gate
+     * to refuse at, so a 403 here means something outside the Twin service refused, and is thrown.
+     *
+     * @throws {TwinNotFoundError} The twin does not exist, or the caller cannot see it — the
+     * surface does not distinguish the two.
+     * @throws {TwinUnauthenticatedError} No valid auth context (401).
+     * @throws {TwinTemporarilyUnavailableError} The request could not be completed (503);
+     * safe to retry unchanged.
+     */
+    getMyTwinPermissions(twinId: string, signal?: AbortSignal): Promise<MyTwinPermissions>;
+
+    /**
+     * Lists one page of the permission entries on every scope the twin owns. Each entry carries
+     * the etag of the scope it lives on, which is the value to send back when mutating that
+     * principal.
+     *
+     * `pagination.nextPage` is emitted unconditionally — it is non-null on the last page too — so
+     * it is not a termination signal. Page until a response comes back with fewer entries than the
+     * limit asked for, or use {@link listAllTwinPermissions}, which does that. On an access-review
+     * surface, stopping early under-reports who holds capabilities on the twin.
+     *
+     * @throws {TwinPermissionsForbiddenError} The caller may see the twin but does not hold
+     * `ManageTwinPermissions` on it (403).
+     * @throws {TwinNotFoundError} The twin does not exist or the caller cannot see it (404).
+     * @throws {TwinValidationError} The limit is out of range, or the pagination token is invalid
+     * or does not match the query it was issued for (400).
+     * @throws {TwinPermissionsConflictError} `ScopesNotProvisioned` — the twin owns no Twinfinity
+     * scope, so there is no permission state to read (409). Retrying will not help.
+     * @throws {TwinTemporarilyUnavailableError} The request could not be completed (503);
+     * safe to retry unchanged.
+     */
+    listTwinPermissions(
+        twinId: string,
+        options?: { page?: string; limit?: number },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<TwinPrincipalPermissionsGet>>;
+
+    /**
+     * Every permission entry on the twin, following the pagination to the end. The whole
+     * access-control list of one twin is a handful of entries, and reviewing it is the point of
+     * the surface, so this — rather than {@link listTwinPermissions} — is what most callers want.
+     *
+     * Throws whatever {@link listTwinPermissions} throws, from whichever page hit it.
+     */
+    listAllTwinPermissions(twinId: string, signal?: AbortSignal): Promise<TwinPrincipalPermissionsGet[]>;
+
+    /**
+     * Replaces the principal's capabilities on the twin, and returns the entry as stored
+     * along with the etag to chain the next write on. `permissions: []` revokes all four
+     * capabilities without removing an entry that carries bits outside this vocabulary.
+     *
+     * `body.etag` may be omitted only for a principal that holds nothing on the twin yet;
+     * see {@link TwinPermissionsPut}. Both etag refusals arrive as
+     * {@link TwinPermissionsConflictError}, carrying the current state to retry from.
+     *
+     * @throws {TwinValidationError} The target is immutable through this surface — the twin's own
+     * default groups and the seeded system principals, marked by
+     * {@link TwinPrincipalPermissionsGet.readOnly} (cause `SystemPrincipalImmutable`) — or the
+     * write asked for `ManageTwinPermissions` on the all-authenticated principal (cause
+     * `ManagePermissionsNotGrantableToAllAuthenticated`), which would make the whole tenant an
+     * administrator of the twin (400).
+     * @throws {TwinPrincipalNotFoundError} No principal carries this id (404).
+     * @throws {TwinNotFoundError} The twin does not exist or the caller cannot see it (404).
+     * @throws {TwinPermissionsForbiddenError} `ManageTwinPermissions` is required (403).
+     * @throws {TwinPermissionsConflictError} `EtagRequired`, `EtagMismatch` or
+     * `ScopesNotProvisioned` (409); the first two carry `currentState`.
+     * @throws {TwinTemporarilyUnavailableError} The request could not be completed (503);
+     * safe to retry unchanged.
+     */
+    setTwinPermissions(
+        twinId: string,
+        principalId: string,
+        body: TwinPermissionsPut,
+        signal?: AbortSignal
+    ): Promise<TwinPrincipalPermissionsGet>;
+
+    /**
+     * Removes the principal from the twin's access control list entirely — including any
+     * bits outside this capability vocabulary, which is what separates it from a
+     * {@link setTwinPermissions} call with an empty list.
+     *
+     * The etag is always required: a delete always replaces existing grants.
+     *
+     * @throws {TwinPrincipalNotFoundError} The principal holds nothing on the twin, so there is
+     * nothing to revoke and no entry to have read an etag from — whatever value was sent (404).
+     * @throws {TwinValidationError} The principal is immutable through this surface (400), decided
+     * before the etag is looked at.
+     * @throws {TwinNotFoundError} The twin does not exist or the caller cannot see it (404).
+     * @throws {TwinPermissionsForbiddenError} `ManageTwinPermissions` is required (403).
+     * @throws {TwinPermissionsConflictError} `EtagMismatch` or `ScopesNotProvisioned` (409).
+     * @throws {TwinTemporarilyUnavailableError} The request could not be completed (503);
+     * safe to retry unchanged.
+     */
+    deleteTwinPermissions(
+        twinId: string,
+        principalId: string,
+        etag: string,
+        signal?: AbortSignal
+    ): Promise<TwinPrincipalPermissionsGet>;
+
+    /**
+     * Returns the three default groups the twin owns — `TwinReaders`, `TwinContributors`,
+     * `TwinAdministrators` — under the ids to name in {@link setTwinPermissions}.
+     *
+     * Not a picker for the principals a twin can be granted to: that is every group in the
+     * tenant, which the Permission service lists. These are the groups the twin itself
+     * owns, whose membership confers its preset capability levels.
+     *
+     * @throws {TwinPermissionsForbiddenError} `ManageTwinPermissions` is required (403).
+     * @throws {TwinNotFoundError} The twin does not exist or the caller cannot see it (404).
+     * @throws {TwinPermissionsConflictError} `ScopesNotProvisioned` (409).
+     * @throws {TwinTemporarilyUnavailableError} The request could not be completed (503);
+     * safe to retry unchanged.
+     */
+    listTwinGroups(twinId: string, signal?: AbortSignal): Promise<TwinGroupsGet>;
+
+    /**
+     * Returns one of the twin's own default groups.
+     *
+     * @throws {TwinPrincipalNotFoundError} The twin does not own this group — thrown even when the
+     * group exists in the tenant and holds capabilities on this twin, since ownership, not
+     * existence, is what this route answers (404).
+     * @throws {TwinNotFoundError} The twin does not exist or the caller cannot see it (404).
+     * @throws {TwinPermissionsForbiddenError} `ManageTwinPermissions` is required (403).
+     * @throws {TwinPermissionsConflictError} `ScopesNotProvisioned` (409).
+     * @throws {TwinTemporarilyUnavailableError} The request could not be completed (503);
+     * safe to retry unchanged.
+     */
+    getTwinGroup(twinId: string, groupId: string, signal?: AbortSignal): Promise<TwinGroupGet>;
+
+    // ---------- Asset-domain permissions ----------
+
+    /**
+     * Lists one page of the principals holding capabilities on the customer-wide asset domain, with
+     * the capabilities each of them holds. The companion administration surface to
+     * {@link getMyPermissions}, which answers only for the caller.
+     *
+     * `pagination.nextPage` is emitted unconditionally — it is non-null on the last page too — so it
+     * is not a termination signal. Page until a response comes back with fewer entries than the
+     * limit asked for, or use {@link listAllAssetPermissions}, which does that. On an access-review
+     * surface, stopping early under-reports who holds capabilities.
+     *
+     * @throws {TwinPermissionsForbiddenError} The caller does not hold `ManageAssetPermissions`
+     * (403).
+     * @throws {TwinValidationError} The limit is out of range, or the pagination token is invalid
+     * (400).
+     * @throws {TwinUnauthenticatedError} No valid auth context (401).
+     * @throws {TwinTemporarilyUnavailableError} The request could not be completed (503);
+     * safe to retry unchanged.
+     */
+    listAssetPermissions(
+        options?: { page?: string; limit?: number },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<AssetPrincipalPermissionsGet>>;
+
+    /** Every entry of {@link listAssetPermissions}, paged to exhaustion. */
+    listAllAssetPermissions(signal?: AbortSignal): Promise<AssetPrincipalPermissionsGet[]>;
+
+    /**
+     * Replaces what one principal holds on the asset domain. Capabilities absent from
+     * `body.permissions` are revoked, and an empty list revokes everything — leaving the principal
+     * with no listing entry at all, exactly as {@link deleteAssetPermissions} does.
+     *
+     * `body.etag` is required whenever the principal already holds capabilities, and may be omitted
+     * only to create the grants of one that holds none.
+     *
+     * @throws {TwinPrincipalNotFoundError} No group in the tenant carries this id (404).
+     * @throws {TwinValidationError} `SystemPrincipalImmutable` — a seeded default group, whose
+     * preset is conferred by membership rather than by writing here — or
+     * `ManagePermissionsNotGrantableToAllAuthenticated` (400).
+     * @throws {AssetPermissionsConflictError} `EtagRequired` or `EtagMismatch` (409), carrying the
+     * current state to retry from.
+     * @throws {TwinPermissionsForbiddenError} The caller does not hold `ManageAssetPermissions`
+     * (403).
+     * @throws {TwinUnauthenticatedError} No valid auth context (401).
+     * @throws {TwinTemporarilyUnavailableError} The request could not be completed (503);
+     * safe to retry unchanged.
+     */
+    setAssetPermissions(
+        principalId: string,
+        body: AssetPermissionsPut,
+        signal?: AbortSignal
+    ): Promise<AssetPrincipalPermissionsGet>;
+
+    /**
+     * Removes the principal from the domain's access control list entirely, answering with it and
+     * an empty capability list.
+     *
+     * The answer carries the `etag` the revocation wrote: it belongs to the domain, not to the
+     * principal, so a revoked principal having no listing entry does not cost the caller one. Chain
+     * the next write on it exactly as with {@link setAssetPermissions}, without re-reading
+     * {@link listAssetPermissions}.
+     *
+     * The etag is always required — a revocation always replaces existing grants — and a request
+     * naming none is refused with a `400` rather than a conflict, before anything else is asked.
+     *
+     * @throws {TwinPrincipalNotFoundError} No group in the tenant carries this id, or it holds
+     * nothing here for a revocation to remove (404).
+     * @throws {TwinValidationError} `SystemPrincipalImmutable` or `EtagRequired` (400).
+     * @throws {AssetPermissionsConflictError} `EtagMismatch` (409).
+     * @throws {TwinPermissionsForbiddenError} The caller does not hold `ManageAssetPermissions`
+     * (403).
+     * @throws {TwinUnauthenticatedError} No valid auth context (401).
+     * @throws {TwinTemporarilyUnavailableError} The request could not be completed (503);
+     * safe to retry unchanged.
+     */
+    deleteAssetPermissions(
+        principalId: string,
+        etag: string,
+        signal?: AbortSignal
+    ): Promise<AssetPrincipalPermissionsGet>;
+
+    /**
+     * Returns the asset domain's default groups — `AssetsReaders`, `AssetsContributors`,
+     * `AssetsAdministrators` — under the ids whose membership confers their preset capabilities.
+     *
+     * A group whose seeding has not completed for this customer is omitted rather than listed under
+     * a placeholder title, so a short list is a state to poll rather than an error.
+     *
+     * @throws {TwinPermissionsForbiddenError} The caller does not hold `ManageAssetPermissions`
+     * (403).
+     * @throws {TwinUnauthenticatedError} No valid auth context (401).
+     * @throws {TwinTemporarilyUnavailableError} The titles could not be resolved (503); safe to
+     * retry unchanged.
+     */
+    listAssetGroups(signal?: AbortSignal): Promise<AssetGroupsGet>;
+
+    /**
+     * Returns one default group by its stable name, case-insensitively.
+     *
+     * @throws {TwinPrincipalNotFoundError} The name is one of the three but its group has not been
+     * seeded for this customer yet — safe to retry (404).
+     * @throws {TwinNotFoundError} The name is not one of the three; retrying will not help (404).
+     * @throws {TwinPermissionsForbiddenError} The caller does not hold `ManageAssetPermissions`
+     * (403).
+     * @throws {TwinUnauthenticatedError} No valid auth context (401).
+     * @throws {TwinTemporarilyUnavailableError} The title could not be resolved (503); safe to
+     * retry unchanged.
+     */
+    getAssetGroup(name: string, signal?: AbortSignal): Promise<AssetGroupGet>;
+
+    /**
+     * 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>;
+}
+
+/**
+ * The `Retry-After` of a 503, in seconds, when the response carried a usable one. The Twin service
+ * sends a delta-seconds value; an HTTP-date is permitted by RFC 7231 and simply yields nothing here
+ * rather than a nonsense delay.
+ */
+function retryAfterSeconds(response: Response): number | undefined {
+    const header = response.headers?.get('Retry-After');
+    if (header === null || header === undefined) return undefined;
+
+    const seconds = Number(header);
+    return Number.isInteger(seconds) && seconds >= 0 ? seconds : undefined;
+}
+
+/**
+ * The batch response body carried by a failed batch, or `undefined` when the body is not one.
+ *
+ * A rolled-back batch answers with per-item results under the status of its *last failing item* --
+ * so the same endpoint returns a batch body under 400, 404 or 409, while a whole-request rejection
+ * (an empty batch, duplicate ids, a body/URL twin mismatch, oversized metadata) returns problem
+ * details under 400 as well. Status alone cannot tell those apart, and branching on it reported
+ * every per-item 400 -- a cross-twin id, a deleted asset, metadata failing its schema -- as a
+ * validation failure with no results for the caller to inspect.
+ */
+async function readBatchResponse(response: Response): Promise<AssetBatchResponse | undefined> {
+    // Parse a clone: json() consumes the stream, and a body that turns out not to be a batch
+    // response still has to be readable as problem details or as text by the caller. Without
+    // clone -- some test doubles -- the probe is skipped rather than risk consuming the body.
+    if (typeof response.clone !== 'function') return undefined;
+    try {
+        const parsed = (await response.clone().json()) as AssetBatchResponse;
+        return Array.isArray(parsed?.results) ? parsed : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+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`;
+    }
+
+    /**
+     * Rooted twins base URL — typically `<host>/sites/<container>/_ps/twins`.
+     * Exposed so callers that want to build content URLs in the same auth
+     * scope as the metadata calls can derive them from here. The bare
+     * `<host>/_ps/twins/...` variant is not necessarily an authorized route
+     * on all deployments.
+     */
+    get baseUrl(): string {
+        return this._baseUrl;
+    }
+
+    listTwins(
+        options?: {
+            relatedTo?: string;
+            includeDeleted?: boolean;
+            page?: string;
+            limit?: number;
+        },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<ListTwinItem>>;
+    /**
+     * @deprecated Use the options-object form: `listTwins({ relatedTo, page, limit }, signal)`.
+     * The positional form has no `includeDeleted` parameter; that is only reachable via the options object.
+     */
+    listTwins(
+        relatedTo?: string,
+        page?: string,
+        limit?: number,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<ListTwinItem>>;
+    async listTwins(
+        optionsOrRelatedTo?:
+            | {
+                  relatedTo?: string;
+                  includeDeleted?: boolean;
+                  page?: string;
+                  limit?: number;
+              }
+            | string,
+        pageOrSignal?: string | AbortSignal,
+        positionalLimit?: number,
+        positionalSignal?: AbortSignal
+    ): Promise<PaginatedResponse<ListTwinItem>> {
+        let relatedTo: string | undefined;
+        let includeDeleted = false;
+        let page: string | undefined;
+        let limit = 100;
+        let signal: AbortSignal | undefined;
+
+        if (typeof optionsOrRelatedTo === 'string') {
+            relatedTo = optionsOrRelatedTo;
+            page = pageOrSignal as string | undefined;
+            limit = positionalLimit ?? 100;
+            signal = positionalSignal;
+        } else {
+            ({ relatedTo, includeDeleted = false, page = undefined, limit = 100 } = optionsOrRelatedTo ?? {});
+            signal = pageOrSignal as AbortSignal | undefined;
+        }
+
+        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());
+        if (includeDeleted) params.set('includeDeleted', 'true');
+
+        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}`);
+    }
+
+    listAllTwins(
+        options?: { relatedTo?: string; includeDeleted?: boolean },
+        signal?: AbortSignal
+    ): Promise<ListTwinItem[]>;
+    /**
+     * @deprecated Use the options-object form: `listAllTwins({ relatedTo }, signal)`.
+     * The positional form has no `includeDeleted` parameter; that is only reachable via the options object.
+     */
+    listAllTwins(relatedTo?: string, signal?: AbortSignal): Promise<ListTwinItem[]>;
+    async listAllTwins(
+        optionsOrRelatedTo?: { relatedTo?: string; includeDeleted?: boolean } | string,
+        signalArg?: AbortSignal
+    ): Promise<ListTwinItem[]> {
+        let relatedTo: string | undefined;
+        let includeDeleted = false;
+        let signal: AbortSignal | undefined;
+
+        if (typeof optionsOrRelatedTo === 'string') {
+            relatedTo = optionsOrRelatedTo;
+            signal = signalArg;
+        } else {
+            ({ relatedTo, includeDeleted = false } = optionsOrRelatedTo ?? {});
+            signal = signalArg;
+        }
+
+        const allTwins: ListTwinItem[] = [];
+        let page: string | undefined = undefined;
+        const limit = 100;
+        const maxPages = 1000;
+
+        for (let pageCount = 0; pageCount < maxPages; pageCount++) {
+            const response: PaginatedResponse<ListTwinItem> = await this.listTwins(
+                { relatedTo, page, limit, includeDeleted },
+                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;
+        }
+
+        // The body decides, not the status: a rolled-back batch is reported as a batch error at
+        // whatever status its last failing item carried, and only a body that is not a batch
+        // response falls through to the status arms below.
+        const batchResponse = await readBatchResponse(response);
+        if (batchResponse) {
+            throw new AssetBatchError(`Asset batch operation failed with status ${response.status}`, batchResponse);
+        }
+
+        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}`);
+        }
+
+        // Reached only where the probe above could not read the body -- a Response without clone(),
+        // which some test doubles are. These two statuses only ever carry a batch response, so read
+        // it directly rather than losing the per-item results to the generic error below.
+        if (response.status === 404 || response.status === 409) {
+            const rolledBack = (await response.json()) as AssetBatchResponse;
+            throw new AssetBatchError(`Asset batch operation failed with status ${response.status}`, rolledBack);
+        }
+
+        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}`);
+    }
+
+    // ---------- Twin-scoped permissions (TWINS-2982) ----------
+
+    async getMyTwinPermissions(twinId: string, signal?: AbortSignal): Promise<MyTwinPermissions> {
+        const response = await this._httpClient.fetch(HttpMethod.Get, `${this._baseUrl}/${twinId}/permissions/me`, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+
+        if (response.ok) return (await response.json()) as MyTwinPermissions;
+        return this._failTwinPermissionsRequest(response, 'read the capabilities on the twin', twinId);
+    }
+
+    async listTwinPermissions(
+        twinId: string,
+        options?: { page?: string; limit?: number },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<TwinPrincipalPermissionsGet>> {
+        const params = new URLSearchParams();
+        if (options?.page !== undefined) params.set('page', options.page);
+        if (options?.limit !== undefined) params.set('limit', options.limit.toString());
+
+        const query = params.toString();
+        const response = await this._httpClient.fetch(
+            HttpMethod.Get,
+            `${this._baseUrl}/${twinId}/permissions${query ? `?${query}` : ''}`,
+            { headers: { Accept: 'application/json' }, signal }
+        );
+
+        if (response.ok) return (await response.json()) as PaginatedResponse<TwinPrincipalPermissionsGet>;
+        return this._failTwinPermissionsRequest(response, 'list the twin permissions', twinId);
+    }
+
+    async listAllTwinPermissions(twinId: string, signal?: AbortSignal): Promise<TwinPrincipalPermissionsGet[]> {
+        const limit = 1000;
+        const entries: TwinPrincipalPermissionsGet[] = [];
+
+        // Paged on a short page rather than on `nextPage`, which the service emits even for the
+        // last page — the same reason `listAllTwins` pages this way.
+        let page: string | undefined;
+        let received: number;
+        do {
+            const response = await this.listTwinPermissions(twinId, { page, limit }, signal);
+            entries.push(...response.data);
+            received = response.data.length;
+            page = response.pagination.nextPage;
+        } while (received >= limit);
+
+        return entries;
+    }
+
+    async setTwinPermissions(
+        twinId: string,
+        principalId: string,
+        body: TwinPermissionsPut,
+        signal?: AbortSignal
+    ): Promise<TwinPrincipalPermissionsGet> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Put,
+            `${this._baseUrl}/${twinId}/permissions/${principalId}`,
+            {
+                headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+                body: JSON.stringify(body),
+                signal
+            }
+        );
+
+        if (response.ok) return (await response.json()) as TwinPrincipalPermissionsGet;
+        return this._failTwinPermissionsRequest(response, 'set the twin permissions', twinId, {
+            id: principalId,
+            label: 'Principal'
+        });
+    }
+
+    async deleteTwinPermissions(
+        twinId: string,
+        principalId: string,
+        etag: string,
+        signal?: AbortSignal
+    ): Promise<TwinPrincipalPermissionsGet> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Delete,
+            `${this._baseUrl}/${twinId}/permissions/${principalId}`,
+            {
+                // The etag travels in the header, which is the transport the surface prefers and
+                // the one that wins when both are present. It is repeated in the body — the other
+                // carrier ADR-0008 documents, and the one the endpoint binds — so that the request
+                // still names an etag if a proxy strips the header, or drops the body of a DELETE.
+                headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'If-Match': etag },
+                body: JSON.stringify({ etag }),
+                signal
+            }
+        );
+
+        if (response.ok) return (await response.json()) as TwinPrincipalPermissionsGet;
+        return this._failTwinPermissionsRequest(response, 'revoke the twin permissions', twinId, {
+            id: principalId,
+            label: 'Principal'
+        });
+    }
+
+    async listTwinGroups(twinId: string, signal?: AbortSignal): Promise<TwinGroupsGet> {
+        const response = await this._httpClient.fetch(HttpMethod.Get, `${this._baseUrl}/${twinId}/groups`, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+
+        if (response.ok) return (await response.json()) as TwinGroupsGet;
+        return this._failTwinPermissionsRequest(response, "list the twin's groups", twinId);
+    }
+
+    async getTwinGroup(twinId: string, groupId: string, signal?: AbortSignal): Promise<TwinGroupGet> {
+        const response = await this._httpClient.fetch(HttpMethod.Get, `${this._baseUrl}/${twinId}/groups/${groupId}`, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+
+        if (response.ok) return (await response.json()) as TwinGroupGet;
+        return this._failTwinPermissionsRequest(response, "get the twin's group", twinId, {
+            id: groupId,
+            label: 'Group'
+        });
+    }
+
+    // ---------- Asset-domain permissions ----------
+
+    async listAssetPermissions(
+        options?: { page?: string; limit?: number },
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<AssetPrincipalPermissionsGet>> {
+        const params = new URLSearchParams();
+        if (options?.page !== undefined) params.set('page', options.page);
+        if (options?.limit !== undefined) params.set('limit', options.limit.toString());
+
+        const query = params.toString();
+        const response = await this._httpClient.fetch(
+            HttpMethod.Get,
+            `${this._baseUrl}/permissions${query ? `?${query}` : ''}`,
+            { headers: { Accept: 'application/json' }, signal }
+        );
+
+        if (response.ok) return (await response.json()) as PaginatedResponse<AssetPrincipalPermissionsGet>;
+        return this._failAssetPermissionsRequest(response, 'list the asset permissions');
+    }
+
+    async listAllAssetPermissions(signal?: AbortSignal): Promise<AssetPrincipalPermissionsGet[]> {
+        const limit = 1000;
+        const entries: AssetPrincipalPermissionsGet[] = [];
+
+        // Paged on a short page rather than on `nextPage`, which the service emits even for the
+        // last page — the same reason `listAllTwinPermissions` pages this way.
+        let page: string | undefined;
+        let received: number;
+        do {
+            const response = await this.listAssetPermissions({ page, limit }, signal);
+            entries.push(...response.data);
+            received = response.data.length;
+            page = response.pagination.nextPage;
+        } while (received >= limit);
+
+        return entries;
+    }
+
+    async setAssetPermissions(
+        principalId: string,
+        body: AssetPermissionsPut,
+        signal?: AbortSignal
+    ): Promise<AssetPrincipalPermissionsGet> {
+        const response = await this._httpClient.fetch(HttpMethod.Put, `${this._baseUrl}/permissions/${principalId}`, {
+            headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+            body: JSON.stringify(body),
+            signal
+        });
+
+        if (response.ok) return (await response.json()) as AssetPrincipalPermissionsGet;
+        return this._failAssetPermissionsRequest(response, 'set the asset permissions', {
+            id: principalId,
+            label: 'Principal'
+        });
+    }
+
+    async deleteAssetPermissions(
+        principalId: string,
+        etag: string,
+        signal?: AbortSignal
+    ): Promise<AssetPrincipalPermissionsGet> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Delete,
+            `${this._baseUrl}/permissions/${principalId}`,
+            {
+                // The etag travels in the header, which is the transport the surface prefers and the
+                // one that wins when both are present. It is repeated in the body — the other
+                // carrier the endpoint binds — so the request still names an etag if a proxy strips
+                // the header, or drops the body of a DELETE.
+                headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'If-Match': etag },
+                body: JSON.stringify({ etag }),
+                signal
+            }
+        );
+
+        if (response.ok) return (await response.json()) as AssetPrincipalPermissionsGet;
+        return this._failAssetPermissionsRequest(response, 'revoke the asset permissions', {
+            id: principalId,
+            label: 'Principal'
+        });
+    }
+
+    async listAssetGroups(signal?: AbortSignal): Promise<AssetGroupsGet> {
+        const response = await this._httpClient.fetch(HttpMethod.Get, `${this._baseUrl}/groups`, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+
+        if (response.ok) return (await response.json()) as AssetGroupsGet;
+        return this._failAssetPermissionsRequest(response, "list the asset domain's default groups");
+    }
+
+    async getAssetGroup(name: string, signal?: AbortSignal): Promise<AssetGroupGet> {
+        const response = await this._httpClient.fetch(
+            HttpMethod.Get,
+            `${this._baseUrl}/groups/${encodeURIComponent(name)}`,
+            { headers: { Accept: 'application/json' }, signal }
+        );
+
+        if (response.ok) return (await response.json()) as AssetGroupGet;
+        return this._failAssetPermissionsRequest(response, "get the asset domain's default group", {
+            id: name,
+            label: 'Group'
+        });
+    }
+
+    /**
+     * Maps a refusal from the customer-wide asset permission surface onto the typed error its
+     * status and cause name. The twin-scoped counterpart of this cannot be reused: its 404s are
+     * about a twin, and this surface has none — a 404 naming no principal means the *name* was
+     * unknown, not that a resource was missing.
+     *
+     * A 404 is dispatched on `item.kind`, which is what separates "that group has not been seeded
+     * for this customer yet", which is worth retrying, from "no such group name", which is not.
+     */
+    private async _failAssetPermissionsRequest(
+        response: Response,
+        action: string,
+        principal?: { id: string; label: string }
+    ): Promise<never> {
+        if (response.status === 401) {
+            throw new TwinUnauthenticatedError('Not authenticated');
+        }
+
+        const errorBody = await readErrorBody(response);
+        switch (response.status) {
+            case 400:
+                throw new TwinValidationError(`Failed to ${action}: ${errorBody.detail}`, errorBody);
+            case 403:
+                // The message is the server's own, never a reason invented here: a Twin service that
+                // could not evaluate the request answers a bodiless 403, and `errorBody.cause` is
+                // what separates that from a genuine `InsufficientPermissions`.
+                throw new TwinPermissionsForbiddenError(`Failed to ${action}: ${errorBody.detail}`, errorBody);
+            case 404:
+                if (errorBody.item?.kind === 'Principal' && principal !== undefined) {
+                    throw new TwinPrincipalNotFoundError(
+                        `${principal.label} ${principal.id} not found on the asset domain`,
+                        errorBody
+                    );
+                }
+                throw new TwinNotFoundError(`Failed to ${action}: ${errorBody.detail}`, errorBody);
+            case 409:
+                throw new AssetPermissionsConflictError(
+                    `Failed to ${action}: ${errorBody.detail}`,
+                    errorBody as AssetPermissionsConflictErrorBody
+                );
+            case 503:
+                throw new TwinTemporarilyUnavailableError(
+                    `Failed to ${action}: ${errorBody.detail}`,
+                    errorBody,
+                    retryAfterSeconds(response)
+                );
+        }
+
+        // A 500 can also mean the Permission service failed: the Twin service answers 503 when the
+        // call threw, but 500 when it returned an upstream failure. Only the 503 half is classified
+        // as retryable here, because the 500 arrives as a ProblemDetails payload with no cause to
+        // recognise it by.
+        throw new Error(`Failed to ${action}: ${response.status} ${response.statusText} - ${errorBody.detail}`);
+    }
+
+    /**
+     * Maps a refusal from the twin-scoped permission surface onto the typed error its status
+     * and cause name. Shared by all six methods because the surface answers them uniformly:
+     * the status is decided by the request's shape and the caller's grants, not by the route.
+     *
+     * A 404 is dispatched on `item.kind`, which is the only thing separating "no such twin, or
+     * none you may see" from "the principal you named is not there" — the two arrive on the
+     * same status from the same route.
+     */
+    private async _failTwinPermissionsRequest(
+        response: Response,
+        action: string,
+        twinId: string,
+        principal?: { id: string; label: string }
+    ): Promise<never> {
+        if (response.status === 401) {
+            throw new TwinUnauthenticatedError('Not authenticated');
+        }
+
+        const errorBody = await readErrorBody(response);
+        switch (response.status) {
+            case 400:
+                throw new TwinValidationError(`Failed to ${action}: ${errorBody.detail}`, errorBody);
+            case 403:
+                // The message is the server's own, never a reason invented here: a 403 does not
+                // always mean "you lack ManageTwinPermissions". `/permissions/me` has no capability
+                // gate at all, and a Twin service that could not evaluate the request answers a
+                // bodiless 403 — `errorBody.cause` is what separates those, so it travels with it.
+                throw new TwinPermissionsForbiddenError(`Failed to ${action}: ${errorBody.detail}`, errorBody);
+            case 404:
+                if (errorBody.item?.kind === 'Principal' && principal !== undefined) {
+                    throw new TwinPrincipalNotFoundError(
+                        `${principal.label} ${principal.id} not found on twin ${twinId}`,
+                        errorBody
+                    );
+                }
+                throw new TwinNotFoundError(`Twin ${twinId} not found`, errorBody);
+            case 409:
+                throw new TwinPermissionsConflictError(
+                    `Failed to ${action}: ${errorBody.detail}`,
+                    errorBody as TwinPermissionsConflictErrorBody
+                );
+            case 503:
+                throw new TwinTemporarilyUnavailableError(
+                    `Failed to ${action}: ${errorBody.detail}`,
+                    errorBody,
+                    retryAfterSeconds(response)
+                );
+        }
+
+        // Note that a 500 can also mean the Permission service failed: the Twin service answers 503
+        // when the call threw, but 500 when it returned an upstream failure. Only the 503 half is
+        // classified as retryable here, because the 500 arrives as a ProblemDetails payload with no
+        // cause to recognise it by.
+        throw new Error(`Failed to ${action}: ${response.status} ${response.statusText} - ${errorBody.detail}`);
+    }
+
+    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}`);
+    }
+}