@twinfinity/permission 6.0.0 → 6.0.1-ci.28952

package/src/PermissionClient.ts

@@ -1,5 +1,13 @@
 import { TwinfinityHttpClient, HttpMethod } from '@twinfinity/authentication';
-import type { PaginatedResponse, User, Group, PutGroupRequest, DeleteGroupRequest, PermissionErrorBody } from './types';
+import type {
+    PaginatedResponse,
+    User,
+    Group,
+    GroupMember,
+    PutGroupRequest,
+    DeleteGroupRequest,
+    PermissionErrorBody
+} from './types';
 import {
     PermissionValidationError,
     PermissionError,
@@ -9,10 +17,24 @@ import {
 } from './errors';
 
 export interface IPermissionClient {
-    listUsers(page?: string, limit?: number, signal?: AbortSignal): Promise<PaginatedResponse<User>>;
-    listGroups(page?: string, limit?: number, signal?: AbortSignal): Promise<PaginatedResponse<Group>>;
+    listUsers(page?: string, limit?: number, q?: string, signal?: AbortSignal): Promise<PaginatedResponse<User>>;
+    listGroups(page?: string, limit?: number, q?: string, signal?: AbortSignal): Promise<PaginatedResponse<Group>>;
     putGroup(id: string, request: PutGroupRequest, signal?: AbortSignal): Promise<Group>;
     deleteGroup(id: string, request: DeleteGroupRequest, signal?: AbortSignal): Promise<Group>;
+    listGroupMembers(
+        groupId: string,
+        page?: string,
+        limit?: number,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<User>>;
+    addGroupMember(groupId: string, userId: string, signal?: AbortSignal): Promise<GroupMember>;
+    removeGroupMember(groupId: string, userId: string, signal?: AbortSignal): Promise<GroupMember>;
+    listUserGroups(
+        userId: string,
+        page?: string,
+        limit?: number,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<Group>>;
 }
 
 function isErrorBody(value: unknown): value is PermissionErrorBody {
@@ -23,11 +45,21 @@ async function readErrorBody(response: Response): Promise<PermissionErrorBody |
     try {
         const json = await response.json();
         return isErrorBody(json) ? json : undefined;
-    } catch {
+    } catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') throw err;
         return undefined;
     }
 }
 
+async function readBodyText(response: Response): Promise<string> {
+    try {
+        return await response.text();
+    } catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') throw err;
+        return '';
+    }
+}
+
 export class PermissionClient implements IPermissionClient {
     private readonly _usersUrl: string;
     private readonly _groupsUrl: string;
@@ -44,11 +76,13 @@ export class PermissionClient implements IPermissionClient {
     async listUsers(
         page: string | undefined = undefined,
         limit = 500,
+        q?: string,
         signal?: AbortSignal
     ): Promise<PaginatedResponse<User>> {
         const params = new URLSearchParams();
         if (page !== undefined) params.set('page', page);
         params.set('limit', limit.toString());
+        if (q) params.set('q', q);
 
         const url = `${this._usersUrl}?${params}`;
 
@@ -70,7 +104,7 @@ export class PermissionClient implements IPermissionClient {
             throw new PermissionForbiddenError(body?.detail ?? 'Insufficient permissions to list users', body);
         }
 
-        const errorText = await response.text();
+        const errorText = await readBodyText(response);
         throw new PermissionError(
             `Failed to list users: ${response.status} ${response.statusText} - ${errorText}`,
             response.status,
@@ -81,11 +115,13 @@ export class PermissionClient implements IPermissionClient {
     async listGroups(
         page: string | undefined = undefined,
         limit = 500,
+        q?: string,
         signal?: AbortSignal
     ): Promise<PaginatedResponse<Group>> {
         const params = new URLSearchParams();
         if (page !== undefined) params.set('page', page);
         params.set('limit', limit.toString());
+        if (q) params.set('q', q);
 
         const url = `${this._groupsUrl}?${params}`;
 
@@ -107,7 +143,7 @@ export class PermissionClient implements IPermissionClient {
             throw new PermissionForbiddenError(body?.detail ?? 'Insufficient permissions to list groups', body);
         }
 
-        const errorText = await response.text();
+        const errorText = await readBodyText(response);
         throw new PermissionError(
             `Failed to list groups: ${response.status} ${response.statusText} - ${errorText}`,
             response.status,
@@ -136,7 +172,8 @@ export class PermissionClient implements IPermissionClient {
             let json: unknown;
             try {
                 json = await response.json();
-            } catch {
+            } catch (err) {
+                if (err instanceof Error && err.name === 'AbortError') throw err;
                 throw new PermissionConflictError('Group conflict', undefined);
             }
             const body = isErrorBody(json) ? json : undefined;
@@ -160,7 +197,7 @@ export class PermissionClient implements IPermissionClient {
             throw new PermissionValidationError(body?.detail ?? 'Group validation failed', body);
         }
 
-        const errorText = await response.text();
+        const errorText = await readBodyText(response);
         throw new PermissionError(
             `Failed to put group: ${response.status} ${response.statusText} - ${errorText}`,
             response.status,
@@ -168,6 +205,170 @@ export class PermissionClient implements IPermissionClient {
         );
     }
 
+    async listGroupMembers(
+        groupId: string,
+        page: string | undefined = undefined,
+        limit = 500,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<User>> {
+        const params = new URLSearchParams();
+        if (page !== undefined) params.set('page', page);
+        params.set('limit', limit.toString());
+
+        const url = `${this._groupsUrl}/${encodeURIComponent(groupId)}/members?${params}`;
+
+        const response = await this._httpClient.fetch(HttpMethod.Get, url, { signal });
+
+        if (response.ok) {
+            return (await response.json()) as PaginatedResponse<User>;
+        }
+
+        if (response.status === 404) {
+            const body = await readErrorBody(response);
+            throw new PermissionNotFoundError(body?.detail ?? `Group '${groupId}' not found`, body);
+        }
+
+        if (response.status === 400) {
+            const body = await readErrorBody(response);
+            throw new PermissionValidationError(body?.detail ?? 'Group member listing validation failed', body);
+        }
+
+        if (response.status === 403) {
+            const body = await readErrorBody(response);
+            throw new PermissionForbiddenError(body?.detail ?? 'Insufficient permissions to list group members', body);
+        }
+
+        const errorText = await readBodyText(response);
+        throw new PermissionError(
+            `Failed to list group members: ${response.status} ${response.statusText} - ${errorText}`,
+            response.status,
+            response.statusText
+        );
+    }
+
+    async addGroupMember(groupId: string, userId: string, signal?: AbortSignal): Promise<GroupMember> {
+        const url = `${this._groupsUrl}/${encodeURIComponent(groupId)}/members/${encodeURIComponent(userId)}`;
+
+        const response = await this._httpClient.fetch(HttpMethod.Put, url, { signal });
+
+        if (response.ok) {
+            return (await response.json()) as GroupMember;
+        }
+
+        if (response.status === 404) {
+            const body = await readErrorBody(response);
+            throw new PermissionNotFoundError(body?.detail ?? 'Group or user not found', body);
+        }
+
+        if (response.status === 400) {
+            const body = await readErrorBody(response);
+            throw new PermissionValidationError(body?.detail ?? 'Cannot modify this group', body);
+        }
+
+        if (response.status === 403) {
+            const body = await readErrorBody(response);
+            throw new PermissionForbiddenError(body?.detail ?? 'Insufficient permissions to add group member', body);
+        }
+
+        if (response.status === 409) {
+            const body = await readErrorBody(response);
+            throw new PermissionConflictError(
+                body?.detail ?? 'Group membership was modified concurrently, please retry',
+                undefined,
+                body
+            );
+        }
+
+        const errorText = await readBodyText(response);
+        throw new PermissionError(
+            `Failed to add group member: ${response.status} ${response.statusText} - ${errorText}`,
+            response.status,
+            response.statusText
+        );
+    }
+
+    async removeGroupMember(groupId: string, userId: string, signal?: AbortSignal): Promise<GroupMember> {
+        const url = `${this._groupsUrl}/${encodeURIComponent(groupId)}/members/${encodeURIComponent(userId)}`;
+
+        const response = await this._httpClient.fetch(HttpMethod.Delete, url, { signal });
+
+        if (response.ok) {
+            return (await response.json()) as GroupMember;
+        }
+
+        if (response.status === 404) {
+            const body = await readErrorBody(response);
+            throw new PermissionNotFoundError(body?.detail ?? 'Group, user, or membership not found', body);
+        }
+
+        if (response.status === 400) {
+            const body = await readErrorBody(response);
+            throw new PermissionValidationError(body?.detail ?? 'Cannot modify this group', body);
+        }
+
+        if (response.status === 403) {
+            const body = await readErrorBody(response);
+            throw new PermissionForbiddenError(body?.detail ?? 'Insufficient permissions to remove group member', body);
+        }
+
+        if (response.status === 409) {
+            const body = await readErrorBody(response);
+            throw new PermissionConflictError(
+                body?.detail ?? 'Group membership was modified concurrently, please retry',
+                undefined,
+                body
+            );
+        }
+
+        const errorText = await readBodyText(response);
+        throw new PermissionError(
+            `Failed to remove group member: ${response.status} ${response.statusText} - ${errorText}`,
+            response.status,
+            response.statusText
+        );
+    }
+
+    async listUserGroups(
+        userId: string,
+        page: string | undefined = undefined,
+        limit = 500,
+        signal?: AbortSignal
+    ): Promise<PaginatedResponse<Group>> {
+        const params = new URLSearchParams();
+        if (page !== undefined) params.set('page', page);
+        params.set('limit', limit.toString());
+
+        const url = `${this._usersUrl}/${encodeURIComponent(userId)}/groups?${params}`;
+
+        const response = await this._httpClient.fetch(HttpMethod.Get, url, { signal });
+
+        if (response.ok) {
+            return (await response.json()) as PaginatedResponse<Group>;
+        }
+
+        if (response.status === 404) {
+            const body = await readErrorBody(response);
+            throw new PermissionNotFoundError(body?.detail ?? `User '${userId}' not found`, body);
+        }
+
+        if (response.status === 400) {
+            const body = await readErrorBody(response);
+            throw new PermissionValidationError(body?.detail ?? 'User group listing validation failed', body);
+        }
+
+        if (response.status === 403) {
+            const body = await readErrorBody(response);
+            throw new PermissionForbiddenError(body?.detail ?? 'Insufficient permissions to list user groups', body);
+        }
+
+        const errorText = await readBodyText(response);
+        throw new PermissionError(
+            `Failed to list user groups: ${response.status} ${response.statusText} - ${errorText}`,
+            response.status,
+            response.statusText
+        );
+    }
+
     async deleteGroup(id: string, request: DeleteGroupRequest, signal?: AbortSignal): Promise<Group> {
         const url = `${this._groupsUrl}/${encodeURIComponent(id)}`;
         const response = await this._httpClient.fetch(HttpMethod.Delete, url, {
@@ -188,7 +389,8 @@ export class PermissionClient implements IPermissionClient {
             let json: unknown;
             try {
                 json = await response.json();
-            } catch {
+            } catch (err) {
+                if (err instanceof Error && err.name === 'AbortError') throw err;
                 throw new PermissionConflictError('Group was modified by another user', undefined);
             }
             const body = isErrorBody(json) ? json : undefined;
@@ -209,7 +411,7 @@ export class PermissionClient implements IPermissionClient {
             throw new PermissionValidationError(body?.detail ?? 'Group deletion validation failed', body);
         }
 
-        const errorText = await response.text();
+        const errorText = await readBodyText(response);
         throw new PermissionError(
             `Failed to delete group: ${response.status} ${response.statusText} - ${errorText}`,
             response.status,

package/src/types.ts

@@ -7,6 +7,14 @@ export interface Pagination {
 export interface PaginatedResponse<T> {
     data: T[];
     pagination: Pagination;
+    /**
+     * The caller's effective permissions on the parent resource that governs every item in the
+     * page — populated by endpoints where the authorization subject is shared across all rows
+     * (currently `GET /groups/{id}/members`, where this reflects the caller's mask on the
+     * group's management scope). Absent for endpoints whose items each have their own
+     * authorization subject.
+     */
+    callerPermissions?: PrincipalPermission[];
 }
 
 export interface User {
@@ -17,26 +25,54 @@ export interface User {
     lastName: string | null;
 }
 
+/**
+ * A user returned from group-membership endpoints. Extends {@link User} with the target user's
+ * effective permissions on the containing group's management scope, reflecting the post-mutation
+ * state after an add/remove.
+ */
+export interface GroupMember extends User {
+    permissions: PrincipalPermission[];
+}
+
 export enum PrincipalType {
     Unknown = 'Unknown',
     DomainGroup = 'DomainGroup',
     Group = 'Group'
 }
 
+/**
+ * The permission bits a subject can hold on a group's management scope.
+ *
+ * - `View` — can see the group and its basic metadata (title, description, display name).
+ * - `Edit` — can create and modify groups.
+ * - `Delete` — can delete the group.
+ * - `ViewMembers` — can list the group's members.
+ * - `ManagePermissions` — can update permissions connected to the group (e.g. grant another user Edit on it).
+ */
+export type PrincipalPermission = 'View' | 'Edit' | 'Delete' | 'ViewMembers' | 'ManagePermissions';
+
 export interface Group {
     id: string;
     ownerSystem: string;
     principalType: PrincipalType;
     title: string;
     displayName: string | null;
+    description: string | null;
     etag: string;
     isEditable: boolean;
+    /**
+     * The effective permission bits the relevant subject holds on this group's management scope.
+     * The subject is the caller on most endpoints, and the target user on `GET /users/{id}/groups`.
+     * An empty array means no permissions are granted.
+     */
+    permissions: PrincipalPermission[];
 }
 
 export interface PutGroupRequest {
     /** Title for the group. Used on create; ignored on update (title is immutable). */
     title: string;
     displayName?: string | null;
+    description?: string | null;
     etag?: string | null;
 }