@twinfinity/permission 6.1.0 → 6.1.2-ci.30738

package/src/PermissionClient.ts

@@ -6,6 +6,8 @@ import type {
     GroupMember,
     PutGroupRequest,
     DeleteGroupRequest,
+    ListUsersOptions,
+    GetUserOptions,
     PermissionErrorBody
 } from './types';
 import {
@@ -17,7 +19,24 @@ import {
 } from './errors';
 
 export interface IPermissionClient {
+    /**
+     * Lists users with keyset pagination and optional filters. `q` is a case-insensitive fuzzy
+     * search across external username, email, first and last name; `externalUsername` and
+     * `email` are case-insensitive exact matches. All filters are AND-combined.
+     *
+     * @throws {PermissionValidationError} On invalid pagination token, out-of-range limit, or too-long filter (400).
+     * @throws {PermissionForbiddenError} On insufficient permissions, including `includeDeleted` without global `Edit` (403).
+     */
+    listUsers(options?: ListUsersOptions, signal?: AbortSignal): Promise<PaginatedResponse<User>>;
     listUsers(page?: string, limit?: number, q?: string, signal?: AbortSignal): Promise<PaginatedResponse<User>>;
+    /**
+     * Gets a single user by their unique ID. Soft-deleted users are reported as not found
+     * unless `includeDeleted` is set.
+     *
+     * @throws {PermissionNotFoundError} When no such user exists, or the user is soft-deleted and `includeDeleted` is false (404).
+     * @throws {PermissionForbiddenError} On insufficient permissions, including `includeDeleted` without global `Edit` (403).
+     */
+    getUser(userId: string, options?: GetUserOptions, signal?: AbortSignal): Promise<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>;
@@ -73,21 +92,40 @@ export class PermissionClient implements IPermissionClient {
         this._groupsUrl = `${base}/_ps/groups`;
     }
 
+    listUsers(options?: ListUsersOptions, signal?: AbortSignal): Promise<PaginatedResponse<User>>;
+    listUsers(page?: string, limit?: number, q?: string, signal?: AbortSignal): Promise<PaginatedResponse<User>>;
     async listUsers(
-        page: string | undefined = undefined,
-        limit = 500,
+        pageOrOptions?: string | ListUsersOptions,
+        limitOrSignal?: number | AbortSignal,
         q?: string,
         signal?: AbortSignal
     ): Promise<PaginatedResponse<User>> {
+        let options: ListUsersOptions;
+        let abortSignal: AbortSignal | undefined;
+        const secondArgIsSignal = limitOrSignal !== undefined && typeof limitOrSignal !== 'number';
+        if (typeof pageOrOptions === 'object') {
+            options = pageOrOptions;
+            abortSignal = secondArgIsSignal ? limitOrSignal : undefined;
+        } else if (secondArgIsSignal) {
+            options = { page: pageOrOptions };
+            abortSignal = limitOrSignal;
+        } else {
+            options = { page: pageOrOptions, limit: limitOrSignal, q };
+            abortSignal = signal;
+        }
+
         const params = new URLSearchParams();
-        if (page !== undefined) params.set('page', page);
-        params.set('limit', limit.toString());
-        if (q) params.set('q', q);
+        if (options.page !== undefined) params.set('page', options.page);
+        params.set('limit', (options.limit ?? 500).toString());
+        if (options.q) params.set('q', options.q);
+        if (options.externalUsername) params.set('externalUsername', options.externalUsername);
+        if (options.email) params.set('email', options.email);
+        if (options.includeDeleted) params.set('includeDeleted', 'true');
 
         const url = `${this._usersUrl}?${params}`;
 
         const response = await this._httpClient.fetch(HttpMethod.Get, url, {
-            signal
+            signal: abortSignal
         });
 
         if (response.ok) {
@@ -112,6 +150,37 @@ export class PermissionClient implements IPermissionClient {
         );
     }
 
+    async getUser(userId: string, options?: GetUserOptions, signal?: AbortSignal): Promise<User> {
+        const params = new URLSearchParams();
+        if (options?.includeDeleted) params.set('includeDeleted', 'true');
+        const query = params.toString();
+
+        const url = `${this._usersUrl}/${encodeURIComponent(userId)}${query ? `?${query}` : ''}`;
+
+        const response = await this._httpClient.fetch(HttpMethod.Get, url, { signal });
+
+        if (response.ok) {
+            return (await response.json()) as User;
+        }
+
+        if (response.status === 404) {
+            const body = await readErrorBody(response);
+            throw new PermissionNotFoundError(body?.detail ?? `User '${userId}' not found`, body);
+        }
+
+        if (response.status === 403) {
+            const body = await readErrorBody(response);
+            throw new PermissionForbiddenError(body?.detail ?? 'Insufficient permissions to get user', body);
+        }
+
+        const errorText = await readBodyText(response);
+        throw new PermissionError(
+            `Failed to get user: ${response.status} ${response.statusText} - ${errorText}`,
+            response.status,
+            response.statusText
+        );
+    }
+
     async listGroups(
         page: string | undefined = undefined,
         limit = 500,

package/src/types.ts

@@ -20,9 +20,63 @@ export interface PaginatedResponse<T> {
 export interface User {
     id: string;
     username: string;
+    /**
+     * The human-readable username from the user's source pool (e.g. PS UserName). Omitted when
+     * not available — the backend drops null fields from responses. Unlike `username` (an opaque
+     * per-pool key), this is the name users recognize; it is not unique.
+     */
+    externalUsername?: string;
     email: string;
-    firstName: string | null;
-    lastName: string | null;
+    firstName?: string;
+    lastName?: string;
+    /**
+     * `true` when the user is soft-deleted; omitted otherwise. Only ever present on responses
+     * requested with `includeDeleted: true`, since deleted users are hidden by default.
+     */
+    deleted?: boolean;
+}
+
+/**
+ * Filters for {@link IPermissionClient.listUsers | listUsers}. All filters are AND-combined.
+ */
+export interface ListUsersOptions {
+    /** Pagination token from a previous response's `pagination.nextPage`. */
+    page?: string;
+    /** Maximum number of items to return (max 1000). Defaults to 500. */
+    limit?: number;
+    /**
+     * Case-insensitive free-text search matched against external username, email, first name,
+     * and last name (never the opaque `username`). Empty strings are treated as "no filter".
+     */
+    q?: string;
+    /**
+     * Case-insensitive exact match on external username. Unlike the fuzzy `q` search this never
+     * matches substrings. May yield 0..n users — the field is not unique. Empty strings are
+     * treated as "no filter".
+     */
+    externalUsername?: string;
+    /**
+     * Case-insensitive exact match on email. Unlike the fuzzy `q` search this never matches
+     * substrings. May yield 0..n users — the field is not unique. Empty strings are treated
+     * as "no filter".
+     */
+    email?: string;
+    /**
+     * When true, includes soft-deleted users. Requires `Edit` on the global
+     * principal-management scope; the request fails with 403 otherwise.
+     */
+    includeDeleted?: boolean;
+}
+
+/**
+ * Options for {@link IPermissionClient.getUser | getUser}.
+ */
+export interface GetUserOptions {
+    /**
+     * When true, allows returning a soft-deleted user. Requires `Edit` on the global
+     * principal-management scope; the request fails with 403 otherwise.
+     */
+    includeDeleted?: boolean;
 }
 
 /**
@@ -37,7 +91,8 @@ export interface GroupMember extends User {
 export enum PrincipalType {
     Unknown = 'Unknown',
     DomainGroup = 'DomainGroup',
-    Group = 'Group'
+    Group = 'Group',
+    User = 'User'
 }
 
 /**