@twinfinity/twin 6.1.0 → 6.1.2-ci.30738

package/src/TwinClient.ts

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