@twinfinity/twin 0.0.0-feature.31596

package/dist/TwinClient.js

@@ -0,0 +1,1487 @@
+import { HttpMethod } from '@twinfinity/authentication';
+import { readT8ClientModelWithFactories, readT8ClientModelWithGeometry, readT8GIModelWithFactories, T8EntityType, T8GIMeshDescriptor, T8GIStyle, T8GIRegion, T8Product, T8Project, T8Unit } from '@twinfinity/t8-client-model';
+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';
+/**
+ * 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) {
+    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) {
+    // 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());
+        return Array.isArray(parsed?.results) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export class TwinClient {
+    _httpClient;
+    _baseUrl;
+    _assetTypeCatalogUrl;
+    constructor(baseUrl, _httpClient) {
+        this._httpClient = _httpClient;
+        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() {
+        return this._baseUrl;
+    }
+    async listTwins(optionsOrRelatedTo, pageOrSignal, positionalLimit, positionalSignal) {
+        let relatedTo;
+        let includeDeleted = false;
+        let page;
+        let limit = 100;
+        let signal;
+        if (typeof optionsOrRelatedTo === 'string') {
+            relatedTo = optionsOrRelatedTo;
+            page = pageOrSignal;
+            limit = positionalLimit ?? 100;
+            signal = positionalSignal;
+        }
+        else {
+            ({ relatedTo, includeDeleted = false, page = undefined, limit = 100 } = optionsOrRelatedTo ?? {});
+            signal = pageOrSignal;
+        }
+        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());
+        }
+        if (response.status === 400) {
+            const errorBody = await readErrorBody(response);
+            throw new TwinValidationError(`Twin listing validation failed: ${errorBody.detail}`, errorBody);
+        }
+        const errorText = await response.text();
+        throw new Error(`Failed to list twins: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+    async listAllTwins(optionsOrRelatedTo, signalArg) {
+        let relatedTo;
+        let includeDeleted = false;
+        let signal;
+        if (typeof optionsOrRelatedTo === 'string') {
+            relatedTo = optionsOrRelatedTo;
+            signal = signalArg;
+        }
+        else {
+            ({ relatedTo, includeDeleted = false } = optionsOrRelatedTo ?? {});
+            signal = signalArg;
+        }
+        const allTwins = [];
+        let page = undefined;
+        const limit = 100;
+        const maxPages = 1000;
+        for (let pageCount = 0; pageCount < maxPages; pageCount++) {
+            const response = 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, signal) {
+        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());
+        }
+        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, options, signal) {
+        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());
+        }
+        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, twinVersion, content, signal) {
+        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}`);
+    }
+    async loadTwinVersion(twinId, twinVersion, projectFactory, productFactory, entityTypeFactory, unitFactory, connectProject, connectProduct, signal) {
+        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(data, projectFactory, productFactory, entityTypeFactory, unitFactory, connectProject, connectProduct);
+    }
+    loadTwin(twin, signal) {
+        return this.loadTwinWithFactories(twin, (T8Project.create), (T8Product.create), T8EntityType.create, T8Unit.create, T8Project.connect, T8Product.connect, signal);
+    }
+    async loadTwinWithFactories(twin, projectFactory, productFactory, entityTypeFactory, unitFactory, connectProject, connectProduct, signal) {
+        let page = 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`);
+    }
+    async loadGeometryInfoVersion(twinId, twinVersion, meshDescriptorFactory, styleFactory, regionFactory, signal) {
+        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, signal) {
+        return this.loadGeometryInfoWithFactories(twin, T8GIMeshDescriptor.create, T8GIStyle.create, T8GIRegion.create, signal);
+    }
+    async loadGeometryInfoWithFactories(twin, meshDescriptorFactory, styleFactory, regionFactory, signal) {
+        let page = undefined;
+        const twinId = typeof twin === 'string' ? twin : twin.id;
+        const specifiedVersion = typeof twin === 'string' ? undefined : twin.version;
+        if (specifiedVersion !== undefined) {
+            return {
+                id: twinId,
+                version: specifiedVersion,
+                model: await this.loadGeometryInfoVersion(twinId, specifiedVersion, meshDescriptorFactory, styleFactory, regionFactory, signal)
+            };
+        }
+        const maxPages = 100;
+        for (let pageCount = 0; pageCount < maxPages; pageCount++) {
+            const versions = await this.listTwinVersions(twinId, { page }, signal);
+            if (versions.data.length === 0) {
+                break;
+            }
+            for (const versionItem of versions.data) {
+                const model = await this.loadGeometryInfoVersion(twinId, versionItem.version, meshDescriptorFactory, styleFactory, regionFactory, signal);
+                if (model !== undefined) {
+                    return {
+                        id: twinId,
+                        version: versionItem.version,
+                        model
+                    };
+                }
+            }
+            page = versions.pagination.nextPage;
+        }
+        throw new Error(`Twin ${twinId} does not have geometry info`);
+    }
+    async loadTwinWithGeometryVersion(twinId, twinVersion, signal) {
+        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, signal) {
+        let page = 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, twin, signal) {
+        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());
+        }
+        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());
+            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, twin, signal) {
+        return this.createOrUpdateTwin(twinId, twin, signal);
+    }
+    async deleteTwin(twinId, etag, signal) {
+        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());
+        }
+        if (response.status === 404) {
+            throw new TwinNotFoundError(`Twin ${twinId} not found`);
+        }
+        if (response.status === 409) {
+            const conflictedTwin = (await response.json());
+            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, etag, signal) {
+        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());
+        }
+        if (response.status === 404) {
+            throw new TwinNotFoundError(`Twin ${twinId} not found`);
+        }
+        if (response.status === 409) {
+            const conflictedTwin = (await response.json());
+            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, twinVersion, signal) {
+        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());
+        }
+        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, signal) {
+        const response = await this._httpClient.fetch(HttpMethod.Get, `${this._baseUrl}/${twinId}/contents`, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+        if (response.ok) {
+            return (await response.json());
+        }
+        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, signal) {
+        const response = await this._httpClient.fetch(HttpMethod.Get, `${this._baseUrl}/${twinId}/diagnostics`, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+        if (response.ok) {
+            return (await response.json());
+        }
+        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, twinVersion, signal) {
+        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());
+        }
+        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, twinVersion, offset = 0, limit = 100, signal) {
+        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());
+        }
+        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, twinVersion, processorId, offset = 0, limit = 100, signal) {
+        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());
+        }
+        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, offset = 0, limit = 100, options, signal) {
+        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());
+        }
+        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, assetId, signal) {
+        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());
+        }
+        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, assets, signal) {
+        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());
+        }
+        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, assetId, asset, signal) {
+        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());
+        }
+        if (response.status === 409) {
+            const conflictedAsset = (await response.json());
+            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, assetId, etag, signal) {
+        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());
+        }
+        if (response.status === 409) {
+            const conflictedAsset = (await response.json());
+            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, assetId, etag) {
+        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());
+        }
+        if (response.status === 409) {
+            const conflictedAsset = (await response.json());
+            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, operations, signal) {
+        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());
+        }
+        // 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());
+            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, ids, signal) {
+        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());
+        }
+        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, assetId, options, signal) {
+        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());
+        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, assetId, attachmentId, signal) {
+        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, assetId, attachmentId, body, signal) {
+        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());
+        if (response.status === 409) {
+            const conflicted = (await response.json());
+            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, file, signal) {
+        // 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, assetId, token, signal) {
+        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());
+        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, assetId, attachmentId, body, signal) {
+        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());
+        if (response.status === 409) {
+            const conflicted = (await response.json());
+            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, assetId, attachmentId, etag, signal) {
+        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());
+        if (response.status === 409) {
+            const conflicted = (await response.json());
+            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, assetId, attachmentId, etag, signal) {
+        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());
+        if (response.status === 409) {
+            const conflicted = (await response.json());
+            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, options = {}, signal) {
+        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());
+        }
+        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, fileId, signal) {
+        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());
+        }
+        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, fileId, twinFile, signal) {
+        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());
+        }
+        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());
+            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, fileId, deleteRequest, signal) {
+        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());
+        }
+        if (response.status === 404) {
+            throw new TwinFileNotFoundError(`Twin file ${fileId} not found`);
+        }
+        if (response.status === 409) {
+            const conflictedFile = (await response.json());
+            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, fileId, etag, signal) {
+        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());
+        }
+        if (response.status === 404) {
+            throw new TwinFileNotFoundError(`Twin file ${fileId} not found`);
+        }
+        if (response.status === 409) {
+            const conflictedFile = (await response.json());
+            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, fileId, signal) {
+        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, fileId, version, signal) {
+        const response = await this._httpClient.fetch(HttpMethod.Get, `${this._baseUrl}/${twinId}/files/${fileId}/versions/${version}`, { signal });
+        if (response.ok) {
+            return (await response.json());
+        }
+        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, fileId, options, signal) {
+        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());
+        }
+        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, fileId, version, signal) {
+        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, twin, signal) {
+        return await this._httpClient.fetch(HttpMethod.Put, `${this._baseUrl}/${twinId}`, {
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(twin),
+            signal
+        });
+    }
+    async createOrUpdateTwinFileRaw(twinId, fileId, twinFile, signal) {
+        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) {
+        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());
+        }
+        // 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, signal) {
+        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());
+        return this._failTwinPermissionsRequest(response, 'read the capabilities on the twin', twinId);
+    }
+    async listTwinPermissions(twinId, options, signal) {
+        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());
+        return this._failTwinPermissionsRequest(response, 'list the twin permissions', twinId);
+    }
+    async listAllTwinPermissions(twinId, signal) {
+        const limit = 1000;
+        const entries = [];
+        // 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;
+        let received;
+        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, principalId, body, signal) {
+        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());
+        return this._failTwinPermissionsRequest(response, 'set the twin permissions', twinId, {
+            id: principalId,
+            label: 'Principal'
+        });
+    }
+    async deleteTwinPermissions(twinId, principalId, etag, signal) {
+        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());
+        return this._failTwinPermissionsRequest(response, 'revoke the twin permissions', twinId, {
+            id: principalId,
+            label: 'Principal'
+        });
+    }
+    async listTwinGroups(twinId, signal) {
+        const response = await this._httpClient.fetch(HttpMethod.Get, `${this._baseUrl}/${twinId}/groups`, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+        if (response.ok)
+            return (await response.json());
+        return this._failTwinPermissionsRequest(response, "list the twin's groups", twinId);
+    }
+    async getTwinGroup(twinId, groupId, signal) {
+        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());
+        return this._failTwinPermissionsRequest(response, "get the twin's group", twinId, {
+            id: groupId,
+            label: 'Group'
+        });
+    }
+    // ---------- Asset-domain permissions ----------
+    async listAssetPermissions(options, signal) {
+        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());
+        return this._failAssetPermissionsRequest(response, 'list the asset permissions');
+    }
+    async listAllAssetPermissions(signal) {
+        const limit = 1000;
+        const entries = [];
+        // 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;
+        let received;
+        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, body, signal) {
+        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());
+        return this._failAssetPermissionsRequest(response, 'set the asset permissions', {
+            id: principalId,
+            label: 'Principal'
+        });
+    }
+    async deleteAssetPermissions(principalId, etag, signal) {
+        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());
+        return this._failAssetPermissionsRequest(response, 'revoke the asset permissions', {
+            id: principalId,
+            label: 'Principal'
+        });
+    }
+    async listAssetGroups(signal) {
+        const response = await this._httpClient.fetch(HttpMethod.Get, `${this._baseUrl}/groups`, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+        if (response.ok)
+            return (await response.json());
+        return this._failAssetPermissionsRequest(response, "list the asset domain's default groups");
+    }
+    async getAssetGroup(name, signal) {
+        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());
+        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.
+     */
+    async _failAssetPermissionsRequest(response, action, principal) {
+        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);
+            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.
+     */
+    async _failTwinPermissionsRequest(response, action, twinId, principal) {
+        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);
+            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) {
+        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());
+    }
+    async listAssetCategories(options, signal) {
+        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());
+        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, signal) {
+        const response = await this._httpClient.fetch(HttpMethod.Get, `${this._assetTypeCatalogUrl}/categories/${categoryId}`, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+        if (response.ok)
+            return (await response.json());
+        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, body, signal) {
+        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());
+        if (response.status === 403)
+            throw new AssetCategoryForbiddenError('Asset category upsert forbidden');
+        if (response.status === 409) {
+            const current = (await response.json());
+            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, etag, signal) {
+        return this._categoryDeleteOrRestore(categoryId, etag, /*isRestore*/ false, signal);
+    }
+    async restoreAssetCategory(categoryId, etag, signal) {
+        return this._categoryDeleteOrRestore(categoryId, etag, /*isRestore*/ true, signal);
+    }
+    async _categoryDeleteOrRestore(categoryId, etag, isRestore, signal) {
+        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());
+        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());
+            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, options, signal) {
+        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());
+        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, options, signal) {
+        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());
+        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, typeId, signal) {
+        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());
+        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, typeId, options, signal) {
+        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());
+        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, typeId, body, signal) {
+        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());
+        if (response.status === 403)
+            throw new AssetTypeForbiddenError('Asset type upsert forbidden');
+        if (response.status === 409) {
+            const current = (await response.json());
+            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, typeId, etag, signal) {
+        return this._typeDeleteOrRestore(categoryId, typeId, etag, /*isRestore*/ false, signal);
+    }
+    async restoreAssetType(categoryId, typeId, etag, signal) {
+        return this._typeDeleteOrRestore(categoryId, typeId, etag, /*isRestore*/ true, signal);
+    }
+    async _typeDeleteOrRestore(categoryId, typeId, etag, isRestore, signal) {
+        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());
+        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());
+            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) {
+        const response = await this._httpClient.fetch(HttpMethod.Get, this._assetTypeCatalogUrl, {
+            headers: { Accept: 'application/json' },
+            signal
+        });
+        if (response.ok)
+            return (await response.json());
+        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}`);
+    }
+}
+//# sourceMappingURL=TwinClient.js.map