[PLT-106969]feat(buckets): accept bucket id or name on file ops; add folderKey/folderPath to getAll

src/models/orchestrator/buckets.models.ts

@@ -19,26 +19,37 @@ import { PaginatedResponse, NonPaginatedResponse, HasPaginationOptions } from '.
  */
 export interface BucketServiceModel {
   /**
-   * Gets all buckets across folders with optional filtering
-   * 
+   * Gets all buckets across folders, or scoped to a specific folder when
+   * folder context is provided.
+   *
+   * Folder scoping is optional and can be supplied as `folderId`, `folderKey`,
+   * or `folderPath` in the options. When none of them is provided the request
+   * is a cross-folder query. Unlike file-operation methods, `getAll()` does
+   * **not** fall back to the SDK's init-time folder key — no folder in options
+   * always means cross-folder.
+   *
    * The method returns either:
    * - A NonPaginatedResponse with data and totalCount (when no pagination parameters are provided)
    * - A paginated result with navigation cursors (when any pagination parameter is provided)
-   * 
-   * @param options - Query options including optional folderId and pagination options
+   *
+   * @param options - Optional folder scoping (`folderId` / `folderKey` / `folderPath`), OData query options, and pagination options
    * @returns Promise resolving to either an array of buckets NonPaginatedResponse<BucketGetResponse> or a PaginatedResponse<BucketGetResponse> when pagination options are used.
    * {@link BucketGetResponse}
    * @example
    * ```typescript
-   * // Get all buckets across folders
+   * // Cross-folder — every bucket the caller can see
    * const allBuckets = await buckets.getAll();
    *
-   * // Get buckets within a specific folder
-   * const folderBuckets = await buckets.getAll({
-   *   folderId: <folderId>
-   * });
+   * // Scoped by folder ID
+   * const folderBuckets = await buckets.getAll({ folderId: <folderId> });
    *
-   * // Get buckets with filtering
+   * // Scoped by folder key (GUID)
+   * await buckets.getAll({ folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
+   *
+   * // Scoped by folder path
+   * await buckets.getAll({ folderPath: 'Shared/Finance' });
+   *
+   * // Filtering
    * const filteredBuckets = await buckets.getAll({
    *   filter: "name eq 'MyBucket'"
    * });
@@ -104,22 +115,30 @@ export interface BucketServiceModel {
   /**
    * Gets metadata for files in a bucket with optional filtering and pagination.
    *
+   * Accepts either a numeric bucket `Id` or a bucket `Name`. When a name is
+   * supplied, the bucket is resolved within the folder scope provided in
+   * `options` — the name lookup runs in the same folder used for the
+   * subsequent file listing.
+   *
    * Folder context can be supplied as `folderId`, `folderKey`, or `folderPath`
    * inside the options.
    *
    * The method returns either:
    * - A NonPaginatedResponse with items array (when no pagination parameters are provided)
    * - A PaginatedResponse with navigation cursors (when any pagination parameter is provided)
    *
-   * @param bucketId - The ID of the bucket to get file metadata from
+   * @param bucket - The bucket's numeric ID or its name
    * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional parameters for filtering and pagination
    * @returns Promise resolving to either an array of files metadata NonPaginatedResponse<BlobItem> or a PaginatedResponse<BlobItem> when pagination options are used.
    * {@link BlobItem}
    * @example
    * ```typescript
-   * // By folder ID
+   * // By bucket ID
    * const fileMetadata = await buckets.getFileMetaData(<bucketId>, { folderId: <folderId> });
    *
+   * // By bucket name
+   * await buckets.getFileMetaData('MyBucket', { folderId: <folderId> });
+   *
    * // By folder key (GUID)
    * await buckets.getFileMetaData(<bucketId>, { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
    *
@@ -139,7 +158,7 @@ export interface BucketServiceModel {
    * ```
    */
   getFileMetaData<T extends BucketGetFileMetaDataWithPaginationOptions = BucketGetFileMetaDataWithPaginationOptions>(
-    bucketId: number,
+    bucket: number | string,
     options?: T,
   ): Promise<
     T extends HasPaginationOptions<T>
@@ -149,16 +168,16 @@ export interface BucketServiceModel {
   /**
    * Gets metadata for files in a bucket — positional `folderId` form.
    *
-   * @deprecated Use the options-object form: `getFileMetaData(bucketId, { folderId })`. See {@link BucketGetFileMetaDataWithPaginationOptions} for the supported options.
+   * @deprecated Use the options-object form: `getFileMetaData(bucket, { folderId })`. See {@link BucketGetFileMetaDataWithPaginationOptions} for the supported options.
    *
-   * @param bucketId - The ID of the bucket to get file metadata from
+   * @param bucket - The bucket's numeric ID or its name
    * @param folderId - Required folder ID (numeric)
    * @param options - Optional parameters for filtering and pagination
    * @returns Promise resolving to either an array of files metadata NonPaginatedResponse<BlobItem> or a PaginatedResponse<BlobItem> when pagination options are used.
    * {@link BlobItem}
    */
   getFileMetaData<T extends BucketGetFileMetaDataWithPaginationOptions = BucketGetFileMetaDataWithPaginationOptions>(
-    bucketId: number,
+    bucket: number | string,
     folderId: number,
     options?: T,
   ): Promise<
@@ -170,19 +189,26 @@ export interface BucketServiceModel {
   /**
    * Gets a direct download URL for a file in the bucket.
    *
+   * Accepts either a numeric bucket `Id` or a bucket `Name`. When a name is
+   * supplied, the bucket is resolved within the folder scope provided in
+   * `options`.
+   *
    * Folder context can be supplied as `folderId`, `folderKey`, or `folderPath`
    * in the options.
    *
-   * @param bucketId - The ID of the bucket
+   * @param bucket - The bucket's numeric ID or its name
    * @param path - The full path to the file
    * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional `expiryInMinutes`
    * @returns Promise resolving to blob file access information
    * {@link BucketGetUriResponse}
    * @example
    * ```typescript
-   * // By folder ID
+   * // By bucket ID
    * await buckets.getReadUri(<bucketId>, '/folder/file.pdf', { folderId: <folderId> });
    *
+   * // By bucket name
+   * await buckets.getReadUri('MyBucket', '/folder/file.pdf', { folderId: <folderId> });
+   *
    * // By folder key (GUID)
    * await buckets.getReadUri(<bucketId>, '/folder/file.pdf', { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
    *
@@ -191,14 +217,14 @@ export interface BucketServiceModel {
    * ```
    */
   getReadUri(
-    bucketId: number,
+    bucket: number | string,
     path: string,
     options?: BucketGetReadUriRequestOptions,
   ): Promise<BucketGetUriResponse>;
   /**
    * Gets a direct download URL for a file in the bucket — options-only form.
    *
-   * @deprecated Use the positional form: `getReadUri(bucketId, path, options?)`. See {@link BucketGetReadUriRequestOptions} for the supported options.
+   * @deprecated Use the positional form: `getReadUri(bucket, path, options?)`. See {@link BucketGetReadUriRequestOptions} for the supported options.
    *
    * @param options - Contains bucketId, folder scoping (`folderId` / `folderKey` / `folderPath`), file path and optional expiry time
    * @returns Promise resolving to blob file access information
@@ -209,21 +235,28 @@ export interface BucketServiceModel {
   /**
    * Uploads a file to a bucket.
    *
+   * Accepts either a numeric bucket `Id` or a bucket `Name`. When a name is
+   * supplied, the bucket is resolved within the folder scope provided in
+   * `options`.
+   *
    * Folder context can be supplied as `folderId`, `folderKey`, or `folderPath`
    * in the options.
    *
-   * @param bucketId - The ID of the bucket to upload to
+   * @param bucket - The bucket's numeric ID or its name
    * @param path - Path where the file should be stored in the bucket
    * @param content - File content to upload
    * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`)
    * @returns Promise resolving bucket upload response
    * {@link BucketUploadResponse}
    * @example
    * ```typescript
-   * // By folder ID
+   * // By bucket ID
    * const file = new File(['file content'], 'example.txt');
    * await buckets.uploadFile(<bucketId>, '/folder/example.txt', file, { folderId: <folderId> });
    *
+   * // By bucket name
+   * await buckets.uploadFile('MyBucket', '/folder/example.txt', file, { folderId: <folderId> });
+   *
    * // By folder key (GUID)
    * await buckets.uploadFile(<bucketId>, '/folder/example.txt', file, { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
    *
@@ -236,15 +269,15 @@ export interface BucketServiceModel {
    * ```
    */
   uploadFile(
-    bucketId: number,
+    bucket: number | string,
     path: string,
     content: Blob | Uint8Array<ArrayBuffer> | File,
     options?: BucketUploadFileRequestOptions,
   ): Promise<BucketUploadResponse>;
   /**
    * Uploads a file to a bucket — options-only form.
    *
-   * @deprecated Use the positional form: `uploadFile(bucketId, path, content, options?)`. See {@link BucketUploadFileRequestOptions} for the supported options.
+   * @deprecated Use the positional form: `uploadFile(bucket, path, content, options?)`. See {@link BucketUploadFileRequestOptions} for the supported options.
    *
    * @param options - Options for file upload including bucket ID, folder scoping (`folderId` / `folderKey` / `folderPath`), path, and content
    * @returns Promise resolving bucket upload response
@@ -255,21 +288,32 @@ export interface BucketServiceModel {
   /**
    * Deletes a file from a bucket
    *
-   * @param bucketId - The ID of the bucket
+   * Accepts either a numeric bucket `Id` or a bucket `Name`. When a name is
+   * supplied, the bucket is resolved within the folder scope provided in
+   * `options`.
+   *
+   * @param bucket - The bucket's numeric ID or its name
    * @param path - The full path to the file to delete
    * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`)
    * @returns Promise resolving when the file is deleted
    * @example
    * ```typescript
-   * // Delete a file from a bucket
+   * // By bucket ID
    * await buckets.deleteFile(<bucketId>, '/folder/file.pdf', { folderId: <folderId> });
+   *
+   * // By bucket name
+   * await buckets.deleteFile('MyBucket', '/folder/file.pdf', { folderId: <folderId> });
    * ```
    */
-  deleteFile(bucketId: number, path: string, options?: BucketDeleteFileOptions): Promise<void>;
+  deleteFile(bucket: number | string, path: string, options?: BucketDeleteFileOptions): Promise<void>;
 
   /**
    * Lists all files in a bucket.
    *
+   * Accepts either a numeric bucket `Id` or a bucket `Name`. When a name is
+   * supplied, the bucket is resolved within the folder scope provided in
+   * `options`.
+   *
    * Returns a flat, recursive listing of all files in the bucket. Supports regex filtering
    * and filter / orderby / select / expand. {@link BucketFile} entries include
    * `isDirectory` so callers can distinguish folders from files.
@@ -278,16 +322,19 @@ export interface BucketServiceModel {
    * - A NonPaginatedResponse with items array (when no pagination parameters are provided)
    * - A PaginatedResponse with navigation cursors (when any pagination parameter is provided)
    *
-   * @param bucketId - The ID of the bucket
+   * @param bucket - The bucket's numeric ID or its name
    * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional parameters for regex filtering, query options, and pagination
    * {@link BucketGetFilesOptions}
    * @returns Promise resolving to either an array of files NonPaginatedResponse<BucketFile> or a PaginatedResponse<BucketFile> when pagination options are used.
    * {@link BucketFile}
    * @example
    * ```typescript
-   * // List all files in the bucket
+   * // By bucket ID
    * const files = await buckets.getFiles(<bucketId>, { folderId: <folderId> });
    *
+   * // By bucket name
+   * const filesByName = await buckets.getFiles('MyBucket', { folderId: <folderId> });
+   *
    * // Filter by regex pattern
    * const pdfs = await buckets.getFiles(<bucketId>, {
    *   folderId: <folderId>,
@@ -311,7 +358,7 @@ export interface BucketServiceModel {
    * ```
    */
   getFiles<T extends BucketGetFilesOptions = BucketGetFilesOptions>(
-    bucketId: number,
+    bucket: number | string,
     options?: T
   ): Promise<
     T extends HasPaginationOptions<T>

src/models/orchestrator/buckets.types.ts

@@ -24,7 +24,12 @@ export interface BucketGetResponse {
 }
 
 export type BucketGetAllOptions = RequestOptions & PaginationOptions & {
+  /** Numeric folder Id. Sent as `X-UIPATH-OrganizationUnitId`. */
   folderId?: number;
+  /** Folder key (GUID). Sent as `X-UIPATH-FolderKey`. */
+  folderKey?: string;
+  /** Slash-delimited folder path (e.g. `'Shared/Finance'`). Sent as `X-UIPATH-FolderPath-Encoded`. */
+  folderPath?: string;
 }
 
 export interface BucketGetByIdOptions extends BaseOptions {}