Add-role-assiment-details (#100)

* add base to use details information

* add new role assignment details types

* support the new endpoints with details

* add missing type

* make things build

* user api implements IUsersApi

Author: teofilomonteiro

src/api/base.ts

@@ -47,7 +47,7 @@ export interface IPagination {
   perPage?: number;
 }
 
-interface IBasePaginationExtended {
+export interface IBasePaginationExtended {
   /**
    * the page number to fetch (default: 1)
    */

src/api/deprecated.ts

@@ -415,7 +415,7 @@ export class DeprecatedApiClient extends BasePermitApi implements IDeprecatedPer
       this.logger.debug(
         `[${response.status}] permit.api.getAssignedRoles(${user}, ${tenant ?? 'all tenants'})`,
       );
-      return response.data;
+      return response.data as RoleAssignmentRead[];
     } catch (err) {
       if (axios.isAxiosError(err)) {
         this.logger.error(

src/api/role-assignments.ts

@@ -5,27 +5,33 @@ import {
   RoleAssignmentsApi as AutogenRoleAssignmentsApi,
   BulkRoleAssignmentReport,
   BulkRoleUnAssignmentReport,
+  PaginatedResultRoleAssignmentDetailedRead,
+  PaginatedResultRoleAssignmentRead,
   RoleAssignmentCreate,
+  RoleAssignmentDetailedRead,
   RoleAssignmentRead,
   RoleAssignmentRemove,
 } from '../openapi';
 import { BASE_PATH } from '../openapi/base';
 
-import { BaseFactsPermitAPI, IPagination, IWaitForSync } from './base';
+import { BaseFactsPermitAPI, IBasePaginationExtended, IWaitForSync } from './base';
 import { ApiContextLevel, ApiKeyLevel } from './context';
 
 export {
   BulkRoleAssignmentReport,
   BulkRoleUnAssignmentReport,
+  PaginatedResultRoleAssignmentDetailedRead,
+  PaginatedResultRoleAssignmentRead,
   RoleAssignmentCreate,
   RoleAssignmentRead,
+  RoleAssignmentDetailedRead,
   RoleAssignmentRemove,
 } from '../openapi';
 
 /**
  * Represents the parameters for listing role assignments.
  */
-export interface IListRoleAssignments extends IPagination {
+export interface IBaseListRoleAssignments extends IBasePaginationExtended {
   /**
    * optional user filter, will only return role assignments granted to this user.
    */
@@ -45,8 +51,33 @@ export interface IListRoleAssignments extends IPagination {
    * optional resource instance filter, will only return (resource) role assignments granted on that resource instance.
    */
   resourceInstance?: string;
+
+  /**
+   * optional detailed flag, will return detailed role assignments.
+   */
+  detailed?: boolean;
 }
 
+type IListRoleAssignmentsIncludeTotalCount = IBaseListRoleAssignments & { includeTotalCount: true };
+
+type IListRoleAssignmentsDetailed = IBaseListRoleAssignments & { detailed: true };
+
+export type IListRoleAssignments =
+  | IBaseListRoleAssignments
+  | IListRoleAssignmentsIncludeTotalCount
+  | IListRoleAssignmentsDetailed;
+
+type ReturnListRoleAssignments<T extends IListRoleAssignments> =
+  T extends IListRoleAssignmentsIncludeTotalCount
+    ? // with total count
+      T extends IListRoleAssignmentsDetailed
+      ? PaginatedResultRoleAssignmentDetailedRead
+      : PaginatedResultRoleAssignmentRead
+    : // without total count
+    T extends IListRoleAssignmentsDetailed
+    ? RoleAssignmentDetailedRead[]
+    : RoleAssignmentRead[];
+
 /**
  * API client for managing role assignments.
  */
@@ -59,7 +90,7 @@ export interface IRoleAssignmentsApi extends IWaitForSync {
    * @throws {@link PermitApiError} If the API returns an error HTTP status code.
    * @throws {@link PermitContextError} If the configured {@link ApiContext} does not match the required endpoint context.
    */
-  list(params: IListRoleAssignments): Promise<RoleAssignmentRead[]>;
+  list<T extends IListRoleAssignments>(params: T): Promise<ReturnListRoleAssignments<T>>;
 
   /**
    * Assigns a role to a user in the scope of a given tenant.
@@ -132,10 +163,29 @@ export class RoleAssignmentsApi extends BaseFactsPermitAPI implements IRoleAssig
    * @throws {@link PermitApiError} If the API returns an error HTTP status code.
    * @throws {@link PermitContextError} If the configured {@link ApiContext} does not match the required endpoint context.
    */
-  public async list(params: IListRoleAssignments): Promise<RoleAssignmentRead[]> {
+  public async list<T extends IListRoleAssignments>(
+    params: T,
+  ): Promise<ReturnListRoleAssignments<T>>;
+  public async list(
+    params: IListRoleAssignments,
+  ): Promise<
+    | Array<RoleAssignmentRead>
+    | Array<RoleAssignmentDetailedRead>
+    | PaginatedResultRoleAssignmentRead
+    | PaginatedResultRoleAssignmentDetailedRead
+  > {
     await this.ensureAccessLevel(ApiKeyLevel.ENVIRONMENT_LEVEL_API_KEY);
     await this.ensureContext(ApiContextLevel.ENVIRONMENT);
-    const { user, tenant, role, resourceInstance, page = 1, perPage = 100 } = params;
+    const {
+      user,
+      tenant,
+      role,
+      resourceInstance,
+      page = 1,
+      perPage = 100,
+      detailed,
+      includeTotalCount,
+    } = params;
     try {
       return (
         await this.roleAssignments.listRoleAssignments({
@@ -144,8 +194,10 @@ export class RoleAssignmentsApi extends BaseFactsPermitAPI implements IRoleAssig
           tenant,
           role,
           resourceInstance,
+          detailed,
           page,
           perPage,
+          includeTotalCount,
         })
       ).data;
     } catch (err) {

src/api/users.ts

@@ -4,8 +4,11 @@ import { IPermitConfig } from '../config';
 import {
   RoleAssignmentsApi as AutogenRoleAssignmentsApi,
   UsersApi as AutogenUsersApi,
+  PaginatedResultRoleAssignmentDetailedRead,
+  PaginatedResultRoleAssignmentRead,
   PaginatedResultUserRead,
   RoleAssignmentCreate,
+  RoleAssignmentDetailedRead,
   RoleAssignmentRead,
   RoleAssignmentRemove,
   UserCreate,
@@ -43,7 +46,7 @@ export interface ICreateOrUpdateUserResult {
   created: boolean;
 }
 
-export interface IGetUserRoles {
+export interface IBaseGetUserRoles {
   /**
    * id or key of the user
    * @type {string}
@@ -56,19 +59,50 @@ export interface IGetUserRoles {
    */
   readonly tenant?: string;
 
+  /**
+   * Whether to return full details about the user, tenant and role
+   * @type {boolean}
+   * @default false
+   */
+  readonly detailed?: boolean;
+
+  /**
+   * If true, returns the list of role assignments and the total count.
+   * @type {boolean}
+   * @default false
+   */
+  readonly includeTotalCount?: boolean;
+
   /**
    * Page number of the results to fetch, starting at 1.
    * @type {number}
+   * @default 1
    */
   readonly page?: number;
 
   /**
    * The number of results per page (max 100).
    * @type {number}
+   * @default 100
    */
   readonly perPage?: number;
 }
 
+type IGetUserRolesWithTotalCount = IBaseGetUserRoles & { includeTotalCount: true };
+type IGetUserRolesWithDetails = IBaseGetUserRoles & { detailed: true };
+
+type IGetUserRoles = IBaseGetUserRoles | IGetUserRolesWithTotalCount | IGetUserRolesWithDetails;
+
+type ReturnIGetUserRolesType<T extends IGetUserRoles> = T extends IGetUserRolesWithTotalCount
+  ? // with total count
+    T extends IGetUserRolesWithDetails
+    ? PaginatedResultRoleAssignmentDetailedRead
+    : PaginatedResultRoleAssignmentRead
+  : // without total count
+  T extends IGetUserRolesWithDetails
+  ? RoleAssignmentDetailedRead[]
+  : RoleAssignmentRead[];
+
 export interface IUsersListParams extends IPagination {
   search?: string;
   role?: string;
@@ -187,7 +221,7 @@ export interface IUsersApi extends IWaitForSync {
    * @throws {@link PermitApiError} If the API returns an error HTTP status code.
    * @throws {@link PermitContextError} If the configured {@link ApiContext} does not match the required endpoint context.
    */
-  getAssignedRoles({ user, tenant, page, perPage }: IGetUserRoles): Promise<RoleAssignmentRead[]>;
+  getAssignedRoles<T extends IGetUserRoles>(params: T): Promise<ReturnIGetUserRolesType<T>>;
 
   /**
    * Creates users in bulk.
@@ -225,7 +259,7 @@ export interface IUsersApi extends IWaitForSync {
 /**
  * The UsersApi class provides methods for interacting with Permit Users.
  */
-export class UsersApi extends BaseFactsPermitAPI {
+export class UsersApi extends BaseFactsPermitAPI implements IUsersApi {
   private users: AutogenUsersApi;
   private roleAssignments: AutogenRoleAssignmentsApi;
   private bulkOperationsApi: BulkOperationsApi;
@@ -559,12 +593,22 @@ export class UsersApi extends BaseFactsPermitAPI {
    * @throws {@link PermitApiError} If the API returns an error HTTP status code.
    * @throws {@link PermitContextError} If the configured {@link ApiContext} does not match the required endpoint context.
    */
+  public async getAssignedRoles<T extends IGetUserRoles>(
+    params: T,
+  ): Promise<ReturnIGetUserRolesType<T>>;
   public async getAssignedRoles({
     user,
     tenant,
     page = 1,
     perPage = 100,
-  }: IGetUserRoles): Promise<RoleAssignmentRead[]> {
+    detailed = false,
+    includeTotalCount = false,
+  }: IGetUserRoles): Promise<
+    | RoleAssignmentRead[]
+    | RoleAssignmentDetailedRead[]
+    | PaginatedResultRoleAssignmentRead
+    | PaginatedResultRoleAssignmentDetailedRead
+  > {
     await this.ensureAccessLevel(ApiKeyLevel.ENVIRONMENT_LEVEL_API_KEY);
     await this.ensureContext(ApiContextLevel.ENVIRONMENT);
     try {
@@ -575,6 +619,8 @@ export class UsersApi extends BaseFactsPermitAPI {
           tenant,
           page,
           perPage,
+          detailed,
+          includeTotalCount,
         })
       ).data;
     } catch (err) {