feat(data-fabric): add roles and directory services

Author: dsuresh-ap

README.md

@@ -265,6 +265,9 @@ The SDK provides access to the following services through modular imports:
 - `CaseInstances` from `@uipath/uipath-typescript/cases` - Manage maestro case executions
 - `Tasks` from `@uipath/uipath-typescript/tasks` - Create and manage tasks
 - `Entities` from `@uipath/uipath-typescript/entities` - Data Fabric entity operations
+- `ChoiceSets` from `@uipath/uipath-typescript/entities` - Data Fabric choice set operations
+- `DataFabricRoles` from `@uipath/uipath-typescript/entities` - List Data Fabric access roles
+- `DataFabricDirectory` from `@uipath/uipath-typescript/entities` - List directory principals and assign Data Fabric roles
 - `Processes` from `@uipath/uipath-typescript/processes` - Manage Orchestrator processes
 - `Buckets` from `@uipath/uipath-typescript/buckets` - Manage storage buckets in Orchestrator
 - `Queues` from `@uipath/uipath-typescript/queues` - Manage Orchestrator queues
@@ -281,7 +284,12 @@ import { Cases, CaseInstances } from '@uipath/uipath-typescript/cases';
 import { Tasks, TaskType } from '@uipath/uipath-typescript/tasks';
 import { Processes } from '@uipath/uipath-typescript/processes';
 import { Buckets } from '@uipath/uipath-typescript/buckets';
-import { Entities } from '@uipath/uipath-typescript/entities';
+import {
+  ChoiceSets,
+  DataFabricDirectory,
+  DataFabricRoles,
+  Entities,
+} from '@uipath/uipath-typescript/entities';
 
 // Initialize SDK
 const sdk = new UiPath({ /* config */ });
@@ -295,6 +303,9 @@ const tasks = new Tasks(sdk);
 const processes = new Processes(sdk);
 const buckets = new Buckets(sdk);
 const entities = new Entities(sdk);
+const choiceSets = new ChoiceSets(sdk);
+const dataFabricRoles = new DataFabricRoles(sdk);
+const dataFabricDirectory = new DataFabricDirectory(sdk);
 
 // Maestro - Get processes and their instances
 const allProcesses = await maestroProcesses.getAll();
@@ -367,6 +378,7 @@ const records = await entities.getAllRecords('entity-uuid', {
   pageSize: 100,
   expansionLevel: 1
 });
+const allChoiceSets = await choiceSets.getAll();
 
 // Insert records
 await entities.insertRecordsById('entity-uuid', [
@@ -381,6 +393,18 @@ await entities.updateRecordsById('entity-uuid', [
 
 // Delete records
 await entities.deleteRecordsById('entity-uuid', ['record-id-1', 'record-id-2']);
+
+// Data Fabric Roles and Directory Access - list and assign access
+const roles = await dataFabricRoles.getAll();
+const dataWriter = roles.find(role => role.name === 'DataWriter');
+
+if (dataWriter) {
+  await dataFabricDirectory.assignRoles(
+    '<identity-group-id>',
+    'Group',
+    [dataWriter.id]
+  );
+}
 ```
 
 </details>

docs/oauth-scopes.md

@@ -67,6 +67,20 @@ This page lists the specific OAuth scopes required in external app for each SDK
 | `getAll()` | `DataFabric.Schema.Read` |
 | `getById()` | `DataFabric.Data.Read` |
 
+## Data Fabric Roles
+
+| Method | OAuth Scope |
+|--------|-------------|
+| `getAll()` | `DataFabric.Data.Read` |
+
+## Data Fabric Directory
+
+| Method | OAuth Scope |
+|--------|-------------|
+| `list()` | `DataFabric.Data.Read` |
+| `getAll()` | `DataFabric.Data.Read` |
+| `assignRoles()` | `DataFabric.Data.Write` |
+
 ## Maestro Processes
 
 | Method | OAuth Scope |

docs/pagination.md

@@ -111,6 +111,19 @@ console.log(`Retrieved ${allAssets.items.length} assets`);
 console.log(`Total count: ${allAssets.totalCount}`);
 ```
 
+### Service-specific Offset Pagination
+
+Some endpoints expose product-native offset parameters instead of the shared cursor/jump wrapper. Data Fabric Directory uses `list({ skip, top })` for a single page, and `getAll({ pageSize })` to fetch every page.
+
+```typescript
+import { DataFabricDirectory } from '@uipath/uipath-typescript/entities';
+
+const directory = new DataFabricDirectory(sdk);
+
+const firstPage = await directory.list({ skip: 0, top: 50 });
+const allPrincipals = await directory.getAll({ pageSize: 100 });
+```
+
 ## Quick Reference Table
 
 | Service | Method | Supports `jumpToPage`? |
@@ -122,6 +135,8 @@ console.log(`Total count: ${allAssets.totalCount}`);
 | Entities | `getAll()` | ✅ Yes |
 | Entities | `getAllRecords()` | ✅ Yes |
 | Entities | `queryRecordsById()` | ✅ Yes |
+| DataFabricDirectory | `list()` | ❌ No |
+| DataFabricDirectory | `getAll()` | ❌ No |
 | Processes | `getAll()` | ✅ Yes |
 | ProcessInstances | `getAll()` | ❌ No |
 | CaseInstances | `getAll()` | ❌ No |

src/models/data-fabric/directory.internal-types.ts

@@ -0,0 +1,24 @@
+import {
+  DataFabricDirectoryEntityType,
+  DataFabricDirectoryEntry,
+} from './directory.types';
+
+export interface DataFabricDirectoryAssignPayload {
+  directoryEntities: Array<{
+    externalId: string;
+    type: DataFabricDirectoryEntityType;
+    resolved: true;
+  }>;
+  roles: string[];
+  isUIEnabled: boolean;
+}
+
+export interface RawDataFabricDirectoryListResponse {
+  totalCount?: number;
+  TotalCount?: number;
+  results?: DataFabricDirectoryEntry[];
+  Results?: DataFabricDirectoryEntry[];
+  value?: DataFabricDirectoryEntry[];
+  Value?: DataFabricDirectoryEntry[];
+  data?: DataFabricDirectoryEntry[];
+}

src/models/data-fabric/directory.models.ts

@@ -0,0 +1,97 @@
+import {
+  DataFabricDirectoryAssignOptions,
+  DataFabricDirectoryAssignmentResult,
+  DataFabricDirectoryEntityTypeInput,
+  DataFabricDirectoryEntry,
+  DataFabricDirectoryGetAllOptions,
+  DataFabricDirectoryListOptions,
+  DataFabricDirectoryListResponse,
+} from './directory.types';
+
+export interface DataFabricDirectoryServiceModel {
+  /**
+   * Lists one page of Data Fabric directory principals and their current roles.
+   *
+   * Returns directory entries with external IDs, principal metadata, and
+   * assigned Data Fabric roles.
+   *
+   * @param options - Optional offset paging options
+   * @returns Promise resolving to {@link DataFabricDirectoryListResponse}
+   *
+   * @example
+   * ```typescript
+   * import { DataFabricDirectory } from '@uipath/uipath-typescript/entities';
+   *
+   * const directory = new DataFabricDirectory(sdk);
+   * const page = await directory.list({ skip: 0, top: 50 });
+   * const firstPrincipal = page.results[0];
+   * ```
+   */
+  list(options?: DataFabricDirectoryListOptions): Promise<DataFabricDirectoryListResponse>;
+
+  /**
+   * Lists all Data Fabric directory principals and their current roles.
+   *
+   * Follows the Data Fabric directory top/skip pagination and returns
+   * normalized entries. Entries without assigned roles include an empty
+   * `roles` array.
+   *
+   * @param options - Optional page-size options
+   * @returns Promise resolving to an array of {@link DataFabricDirectoryEntry}
+   *
+   * @example
+   * ```typescript
+   * import { DataFabricDirectory } from '@uipath/uipath-typescript/entities';
+   *
+   * const directory = new DataFabricDirectory(sdk);
+   * const principals = await directory.getAll({ pageSize: 100 });
+   * ```
+   */
+  getAll(options?: DataFabricDirectoryGetAllOptions): Promise<DataFabricDirectoryEntry[]>;
+
+  /**
+   * Assigns Data Fabric roles to one or more principals.
+   *
+   * The Data Fabric API replaces the role set for each principal, so this
+   * method preserves existing roles by default and posts the union of current
+   * and requested role IDs.
+   *
+   * Role IDs can be discovered with `DataFabricRoles.getAll()`. Set
+   * `preserveExisting: false` only when intentionally replacing a principal's
+   * Data Fabric role set.
+   *
+   * @param principalIds - Principal external ID or IDs
+   * @param principalType - Principal type
+   * @param roleIds - Data Fabric role IDs to assign
+   * @param options - Optional assignment behavior
+   * @returns Promise resolving to assignment results per principal
+   *
+   * @example
+   * ```typescript
+   * import { DataFabricDirectory, DataFabricRoles } from '@uipath/uipath-typescript/entities';
+   *
+   * const roles = new DataFabricRoles(sdk);
+   * const directory = new DataFabricDirectory(sdk);
+   *
+   * const dataWriter = (await roles.getAll()).find(role => role.name === 'DataWriter');
+   * if (!dataWriter) {
+   *   throw new Error('DataWriter role not found');
+   * }
+   *
+   * await directory.assignRoles('<identity-group-id>', 'Group', [dataWriter.id]);
+   * ```
+   *
+   * @example
+   * ```typescript
+   * await directory.assignRoles('<identity-user-id>', 'User', ['<role-id>'], {
+   *   preserveExisting: false,
+   * });
+   * ```
+   */
+  assignRoles(
+    principalIds: string | string[],
+    principalType: DataFabricDirectoryEntityTypeInput,
+    roleIds: string[],
+    options?: DataFabricDirectoryAssignOptions
+  ): Promise<DataFabricDirectoryAssignmentResult[]>;
+}

src/models/data-fabric/directory.types.ts

@@ -0,0 +1,81 @@
+export enum DataFabricDirectoryEntityType {
+  /** Identity user, robot user, or directory robot principal. */
+  User = 0,
+  /** Identity group principal. */
+  Group = 1,
+  /** External application principal. */
+  Application = 2,
+}
+
+export type DataFabricDirectoryEntityTypeInput =
+  | DataFabricDirectoryEntityType
+  | 'User'
+  | 'user'
+  | 'Group'
+  | 'group'
+  | 'DirectoryGroup'
+  | 'directoryGroup'
+  | 'Application'
+  | 'application'
+  | 'ExternalApplication'
+  | 'externalApplication'
+  | 'DirectoryExternalApplication'
+  | 'directoryExternalApplication'
+  | 'Robot'
+  | 'robot'
+  | 'DirectoryRobot'
+  | 'directoryRobot'
+  | 'DirectoryRobotUser'
+  | 'directoryRobotUser';
+
+export interface DataFabricDirectoryRole {
+  id: string;
+  name?: string;
+  [key: string]: unknown;
+}
+
+export interface DataFabricDirectoryEntry {
+  externalId: string;
+  name?: string;
+  email?: string;
+  type?: string | number;
+  roles: DataFabricDirectoryRole[];
+  objectType?: string;
+  isUIEnabled?: boolean;
+  [key: string]: unknown;
+}
+
+export interface DataFabricDirectoryListOptions {
+  skip?: number;
+  top?: number;
+}
+
+export interface DataFabricDirectoryGetAllOptions {
+  pageSize?: number;
+}
+
+export interface DataFabricDirectoryListResponse {
+  totalCount?: number;
+  results: DataFabricDirectoryEntry[];
+}
+
+export interface DataFabricDirectoryAssignOptions {
+  /**
+   * Preserve the principal's current Data Fabric roles.
+   *
+   * Defaults to true because the Data Fabric role assignment endpoint replaces
+   * the role set for each principal.
+   */
+  preserveExisting?: boolean;
+  /**
+   * Enables Data Fabric UI access for the assigned principal.
+   *
+   * Defaults to true.
+   */
+  uiEnabled?: boolean;
+}
+
+export interface DataFabricDirectoryAssignmentResult {
+  principalId: string;
+  roleIds: string[];
+}

src/models/data-fabric/index.ts

@@ -1,4 +1,8 @@
 export * from './entities.types';
 export * from './entities.models';
 export * from './choicesets.types';
-export * from './choicesets.models'; 
+export * from './choicesets.models';
+export * from './roles.types';
+export * from './roles.models';
+export * from './directory.types';
+export * from './directory.models';

src/models/data-fabric/roles.internal-types.ts

@@ -0,0 +1,9 @@
+import { DataFabricRole } from './roles.types';
+
+export interface RawDataFabricRoleListResponse {
+  results?: DataFabricRole[];
+  Results?: DataFabricRole[];
+  value?: DataFabricRole[];
+  Value?: DataFabricRole[];
+  data?: DataFabricRole[];
+}

src/models/data-fabric/roles.models.ts

@@ -0,0 +1,29 @@
+import { DataFabricRole, DataFabricRoleGetAllOptions } from './roles.types';
+
+export interface DataFabricRoleServiceModel {
+  /**
+   * Lists Data Fabric access roles.
+   *
+   * Returns tenant Data Fabric roles such as Admin, Designer, DataWriter, and
+   * DataReader. Role IDs from this method can be passed to
+   * `DataFabricDirectory.assignRoles()`.
+   *
+   * @param options - Optional query options
+   * @returns Promise resolving to an array of {@link DataFabricRole}
+   *
+   * @example
+   * ```typescript
+   * import { DataFabricRoles } from '@uipath/uipath-typescript/entities';
+   *
+   * const roles = new DataFabricRoles(sdk);
+   * const allRoles = await roles.getAll();
+   * const dataWriter = allRoles.find(role => role.name === 'DataWriter');
+   * ```
+   *
+   * @example
+   * ```typescript
+   * const rolesWithoutStats = await roles.getAll({ stats: false });
+   * ```
+   */
+  getAll(options?: DataFabricRoleGetAllOptions): Promise<DataFabricRole[]>;
+}

src/models/data-fabric/roles.types.ts

@@ -0,0 +1,17 @@
+export interface DataFabricRole {
+  id: string;
+  name: string;
+  displayName?: string;
+  description?: string;
+  isSystem?: boolean;
+  [key: string]: unknown;
+}
+
+export interface DataFabricRoleGetAllOptions {
+  /**
+   * Include role statistics in the response.
+   *
+   * Defaults to true to match the Data Fabric UI and CLI role-list flow.
+   */
+  stats?: boolean;
+}