@twinfinity/twin 6.1.0 → 6.1.2-ci.30738

package/dist/TwinClient.js

@@ -1,6 +1,42 @@
 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, readErrorBody } from './errors';
+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;
@@ -21,7 +57,22 @@ export class TwinClient {
     get baseUrl() {
         return this._baseUrl;
     }
-    async listTwins(relatedTo, page = undefined, limit = 100, signal) {
+    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);
@@ -29,6 +80,8 @@ export class TwinClient {
             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' },
@@ -44,13 +97,24 @@ export class TwinClient {
         const errorText = await response.text();
         throw new Error(`Failed to list twins: ${response.status} ${response.statusText} - ${errorText}`);
     }
-    async listAllTwins(relatedTo, signal) {
+    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, signal);
+            const response = await this.listTwins({ relatedTo, page, limit, includeDeleted }, signal);
             allTwins.push(...response.data);
             if (response.data.length < limit) {
                 break;
@@ -511,6 +575,13 @@ export class TwinClient {
         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);
@@ -519,9 +590,12 @@ export class TwinClient {
             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 batchResponse = (await response.json());
-            throw new AssetBatchError(`Asset batch operation failed with status ${response.status}`, batchResponse);
+            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}`);
@@ -900,6 +974,247 @@ export class TwinClient {
         }
         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, {