@uipath/uipath-typescript 1.4.0 → 1.4.1

package/dist/buckets/index.d.ts

@@ -439,10 +439,6 @@ interface BucketGetUriOptions extends BaseOptions {
      * The ID of the bucket
      */
     bucketId: number;
-    /**
-     * The ID of the folder
-     */
-    folderId: number;
     /**
      * The full path to the BlobFile
      */
@@ -453,9 +449,23 @@ interface BucketGetUriOptions extends BaseOptions {
     expiryInMinutes?: number;
 }
 /**
- * Request options for getting a read URI for a file in a bucket
+ * Optional parameters for the preferred `getReadUri(bucketId, path, options?)` form.
+ * Contains folder scoping (`folderId` / `folderKey` / `folderPath`),
+ * `expiryInMinutes`, and standard query options (`expand`, `select`).
+ */
+interface BucketGetReadUriRequestOptions extends BaseOptions, FolderScopedOptions {
+    /**
+     * URL expiration time in minutes (0 for default)
+     */
+    expiryInMinutes?: number;
+}
+/**
+ * @deprecated Use the positional form: `getReadUri(bucketId, path, options?)`.
+ * See {@link BucketGetReadUriRequestOptions} for the supported options.
+ *
+ * Request options for getting a read URI for a file in a bucket.
  */
-interface BucketGetReadUriOptions extends BucketGetUriOptions {
+interface BucketGetReadUriOptions extends BucketGetUriOptions, FolderScopedOptions {
 }
 /**
  * Request options for getting files in a bucket
@@ -469,7 +479,7 @@ interface BucketGetFileMetaDataOptions {
 /**
  * Request options for getting files in a bucket with pagination support
  */
-type BucketGetFileMetaDataWithPaginationOptions = BucketGetFileMetaDataOptions & PaginationOptions;
+type BucketGetFileMetaDataWithPaginationOptions = BucketGetFileMetaDataOptions & PaginationOptions & FolderScopedOptions;
 /**
  * Response from the GetFiles API
  */
@@ -544,17 +554,23 @@ type BucketGetFilesOptions = RequestOptions & PaginationOptions & FolderScopedOp
 interface BucketDeleteFileOptions extends FolderScopedOptions {
 }
 /**
- * Options for uploading files to a bucket
+ * Optional parameters for the preferred
+ * `uploadFile(bucketId, path, content, options?)` form. Contains folder
+ * scoping (`folderId` / `folderKey` / `folderPath`).
+ */
+interface BucketUploadFileRequestOptions extends FolderScopedOptions {
+}
+/**
+ * @deprecated Use the positional form: `uploadFile(bucketId, path, content, options?)`.
+ * See {@link BucketUploadFileRequestOptions} for the supported options.
+ *
+ * Options for uploading files to a bucket.
  */
-interface BucketUploadFileOptions {
+interface BucketUploadFileOptions extends FolderScopedOptions {
     /**
      * The ID of the bucket to upload to
      */
     bucketId: number;
-    /**
-     * The folder/organization unit ID for context
-     */
-    folderId: number;
     /**
      * Path where the file should be stored in the bucket
      */
@@ -672,81 +688,128 @@ interface BucketServiceModel {
      */
     getByName(name: string, options?: BucketGetByNameOptions): Promise<BucketGetResponse>;
     /**
-     * Gets metadata for files in a bucket with optional filtering and pagination
+     * Gets metadata for files in a bucket with optional filtering and pagination.
+     *
+     * 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 folderId - Required folder ID for organization unit context
-     * @param options - Optional parameters for filtering, pagination and access URL generation
+     * @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
-     * // Get metadata for all files in a bucket
-     * const fileMetadata = await buckets.getFileMetaData(<bucketId>, <folderId>);
+     * // By folder ID
+     * const fileMetadata = await buckets.getFileMetaData(<bucketId>, { folderId: <folderId> });
      *
-     * // Get file metadata with a specific prefix
-     * const prefixMetadata = await buckets.getFileMetaData(<bucketId>, <folderId>, {
-     *   prefix: '/folder1'
-     * });
+     * // By folder key (GUID)
+     * await buckets.getFileMetaData(<bucketId>, { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
+     *
+     * // By folder path
+     * await buckets.getFileMetaData(<bucketId>, { folderPath: 'Shared/Finance' });
+     *
+     * // Filter by prefix
+     * await buckets.getFileMetaData(<bucketId>, { folderId: <folderId>, prefix: '/folder1' });
      *
      * // First page with pagination
-     * const page1 = await buckets.getFileMetaData(<bucketId>, <folderId>, { pageSize: 10 });
+     * const page1 = await buckets.getFileMetaData(<bucketId>, { folderId: <folderId>, pageSize: 10 });
      *
      * // Navigate using cursor
      * if (page1.hasNextPage) {
-     *   const page2 = await buckets.getFileMetaData(<bucketId>, <folderId>, { cursor: page1.nextCursor });
+     *   const page2 = await buckets.getFileMetaData(<bucketId>, { folderId: <folderId>, cursor: page1.nextCursor });
      * }
      * ```
      */
+    getFileMetaData<T extends BucketGetFileMetaDataWithPaginationOptions = BucketGetFileMetaDataWithPaginationOptions>(bucketId: number, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BlobItem> : NonPaginatedResponse<BlobItem>>;
+    /**
+     * 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.
+     *
+     * @param bucketId - The ID of the bucket to get file metadata from
+     * @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, folderId: number, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BlobItem> : NonPaginatedResponse<BlobItem>>;
     /**
-     * Gets a direct download URL for a file in the bucket
+     * Gets a direct download URL for a file in the bucket.
+     *
+     * Folder context can be supplied as `folderId`, `folderKey`, or `folderPath`
+     * in the options.
      *
-     * @param options - Contains bucketId, folderId, file path and optional expiry time
+     * @param bucketId - The ID of the bucket
+     * @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
-     * // Get download URL for a file
-     * const fileAccess = await buckets.getReadUri({
-     *   bucketId: <bucketId>,
-     *   folderId: <folderId>,
-     *   path: '/folder/file.pdf'
-     * });
+     * // By folder ID
+     * await buckets.getReadUri(<bucketId>, '/folder/file.pdf', { folderId: <folderId> });
+     *
+     * // By folder key (GUID)
+     * await buckets.getReadUri(<bucketId>, '/folder/file.pdf', { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
+     *
+     * // By folder path
+     * await buckets.getReadUri(<bucketId>, '/folder/file.pdf', { folderPath: 'Shared/Finance' });
      * ```
      */
+    getReadUri(bucketId: number, 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.
+     *
+     * @param options - Contains bucketId, folder scoping (`folderId` / `folderKey` / `folderPath`), file path and optional expiry time
+     * @returns Promise resolving to blob file access information
+     * {@link BucketGetUriResponse}
+     */
     getReadUri(options: BucketGetReadUriOptions): Promise<BucketGetUriResponse>;
     /**
-     * Uploads a file to a bucket
+     * Uploads a file to a bucket.
      *
-     * @param options - Options for file upload including bucket ID, folder ID, path, content, and optional parameters
+     * Folder context can be supplied as `folderId`, `folderKey`, or `folderPath`
+     * in the options.
+     *
+     * @param bucketId - The ID of the bucket to upload to
+     * @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
-     * // Upload a file from browser
+     * // By folder ID
      * const file = new File(['file content'], 'example.txt');
-     * const result = await buckets.uploadFile({
-     *   bucketId: <bucketId>,
-     *   folderId: <folderId>,
-     *   path: '/folder/example.txt',
-     *   content: file
-     * });
+     * await buckets.uploadFile(<bucketId>, '/folder/example.txt', file, { folderId: <folderId> });
+     *
+     * // By folder key (GUID)
+     * await buckets.uploadFile(<bucketId>, '/folder/example.txt', file, { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
+     *
+     * // By folder path
+     * await buckets.uploadFile(<bucketId>, '/folder/example.txt', file, { folderPath: 'Shared/Finance' });
      *
      * // In Node env with Uint8Array or Buffer
      * const content = new TextEncoder().encode('file content');
-     * const result = await buckets.uploadFile({
-     *   bucketId: <bucketId>,
-     *   folderId: <folderId>,
-     *   path: '/folder/example.txt',
-     *   content,
-     * });
+     * await buckets.uploadFile(<bucketId>, '/folder/example.txt', content, { folderId: <folderId> });
      * ```
      */
+    uploadFile(bucketId: number, 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.
+     *
+     * @param options - Options for file upload including bucket ID, folder scoping (`folderId` / `folderKey` / `folderPath`), path, and content
+     * @returns Promise resolving bucket upload response
+     * {@link BucketUploadResponse}
+     */
     uploadFile(options: BucketUploadFileOptions): Promise<BucketUploadResponse>;
     /**
      * Deletes a file from a bucket
@@ -897,16 +960,19 @@ declare class BucketService extends FolderScopedService implements BucketService
      */
     getAll<T extends BucketGetAllOptions = BucketGetAllOptions>(options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BucketGetResponse> : NonPaginatedResponse<BucketGetResponse>>;
     /**
-     * Gets metadata for files in a bucket with optional filtering and pagination
+     * Gets metadata for files in a bucket with optional filtering and pagination.
+     *
+     * 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 folderId - Required folder ID for organization unit context
-     * @param options - Optional parameters for filtering, pagination and access URL generation
+     * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional parameters for filtering and pagination
      * @returns Promise resolving to the list of file metadata in the bucket or paginated result
+     * {@link BlobItem}
      *
      * @example
      * ```typescript
@@ -914,29 +980,52 @@ declare class BucketService extends FolderScopedService implements BucketService
      *
      * const buckets = new Buckets(sdk);
      *
-     * // Get metadata for all files in a bucket
-     * const fileMetadata = await buckets.getFileMetaData(123, 456);
+     * // By folder ID
+     * const fileMetadata = await buckets.getFileMetaData(<bucketId>, { folderId: <folderId> });
      *
-     * // Get file metadata with a specific prefix
-     * const fileMetadata = await buckets.getFileMetaData(123, 456, {
-     *   prefix: '/folder1'
-     * });
+     * // By folder key (GUID)
+     * await buckets.getFileMetaData(<bucketId>, { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
+     *
+     * // By folder path
+     * await buckets.getFileMetaData(<bucketId>, { folderPath: 'Shared/Finance' });
+     *
+     * // Filter by prefix
+     * await buckets.getFileMetaData(<bucketId>, { folderId: <folderId>, prefix: '/folder1' });
      *
      * // First page with pagination
-     * const page1 = await buckets.getFileMetaData(123, 456, { pageSize: 10 });
+     * const page1 = await buckets.getFileMetaData(<bucketId>, { folderId: <folderId>, pageSize: 10 });
      *
      * // Navigate using cursor
      * if (page1.hasNextPage) {
-     *   const page2 = await buckets.getFileMetaData(123, 456, { cursor: page1.nextCursor });
+     *   const page2 = await buckets.getFileMetaData(<bucketId>, { folderId: <folderId>, cursor: page1.nextCursor });
      * }
      * ```
      */
+    getFileMetaData<T extends BucketGetFileMetaDataWithPaginationOptions = BucketGetFileMetaDataWithPaginationOptions>(bucketId: number, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BlobItem> : NonPaginatedResponse<BlobItem>>;
+    /**
+     * 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.
+     *
+     * @param bucketId - The ID of the bucket to get file metadata from
+     * @param folderId - Required folder ID (numeric)
+     * @param options - Optional parameters for filtering and pagination
+     * @returns Promise resolving to the list of file metadata in the bucket or paginated result
+     * {@link BlobItem}
+     */
     getFileMetaData<T extends BucketGetFileMetaDataWithPaginationOptions = BucketGetFileMetaDataWithPaginationOptions>(bucketId: number, folderId: number, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BlobItem> : NonPaginatedResponse<BlobItem>>;
     /**
-     * Uploads a file to a bucket
+     * Uploads a file to a bucket.
+     *
+     * Folder context can be supplied as `folderId`, `folderKey`, or `folderPath`
+     * in the options.
      *
-     * @param options - Options for file upload including bucket ID, folder ID, path, content, and optional parameters
+     * @param bucketId - The ID of the bucket to upload to
+     * @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 to a response with success status and HTTP status code
+     * {@link BucketUploadResponse}
      *
      * @example
      * ```typescript
@@ -944,31 +1033,43 @@ declare class BucketService extends FolderScopedService implements BucketService
      *
      * const buckets = new Buckets(sdk);
      *
-     * // Upload a file from browser
+     * // By folder ID
      * const file = new File(['file content'], 'example.txt');
-     * const result = await buckets.uploadFile({
-     *   bucketId: 123,
-     *   folderId: 456,
-     *   path: '/folder/example.txt',
-     *   content: file
-     * });
+     * await buckets.uploadFile(<bucketId>, '/folder/example.txt', file, { folderId: <folderId> });
+     *
+     * // By folder key (GUID)
+     * await buckets.uploadFile(<bucketId>, '/folder/example.txt', file, { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
+     *
+     * // By folder path
+     * await buckets.uploadFile(<bucketId>, '/folder/example.txt', file, { folderPath: 'Shared/Finance' });
      *
      * // In Node env with Buffer
      * const buffer = Buffer.from('file content');
-     * const result = await buckets.uploadFile({
-     *   bucketId: 123,
-     *   folderId: 456,
-     *   path: '/folder/example.txt',
-     *   content: buffer
-     * });
+     * await buckets.uploadFile(<bucketId>, '/folder/example.txt', buffer, { folderId: <folderId> });
      * ```
      */
+    uploadFile(bucketId: number, 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.
+     *
+     * @param options - Options for file upload including bucket ID, folder scoping (`folderId` / `folderKey` / `folderPath`), path, and content
+     * @returns Promise resolving to a response with success status and HTTP status code
+     * {@link BucketUploadResponse}
+     */
     uploadFile(options: BucketUploadFileOptions): Promise<BucketUploadResponse>;
     /**
-     * Gets a direct download URL for a file in the bucket
+     * Gets a direct download URL for a file in the bucket.
+     *
+     * Folder context can be supplied as `folderId`, `folderKey`, or `folderPath`
+     * inside the options.
      *
-     * @param options - Contains bucketId, folderId, file path and optional expiry time
+     * @param bucketId - The ID of the bucket
+     * @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
@@ -976,14 +1077,26 @@ declare class BucketService extends FolderScopedService implements BucketService
      *
      * const buckets = new Buckets(sdk);
      *
-     * // Get download URL for a file
-     * const fileAccess = await buckets.getReadUri({
-     *   bucketId: 123,
-     *   folderId: 456,
-     *   path: '/folder/file.pdf'
-     * });
+     * // By folder ID
+     * await buckets.getReadUri(<bucketId>, '/folder/file.pdf', { folderId: <folderId> });
+     *
+     * // By folder key (GUID)
+     * await buckets.getReadUri(<bucketId>, '/folder/file.pdf', { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
+     *
+     * // By folder path
+     * await buckets.getReadUri(<bucketId>, '/folder/file.pdf', { folderPath: 'Shared/Finance' });
      * ```
      */
+    getReadUri(bucketId: number, 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.
+     *
+     * @param options - Contains bucketId, folder scoping (`folderId` / `folderKey` / `folderPath`), file path and optional expiry time
+     * @returns Promise resolving to blob file access information
+     * {@link BucketGetUriResponse}
+     */
     getReadUri(options: BucketGetReadUriOptions): Promise<BucketGetUriResponse>;
     /**
      * Uploads content to the provided URI
@@ -996,8 +1109,8 @@ declare class BucketService extends FolderScopedService implements BucketService
      * Private method to handle common URI request logic
      * @param endpoint - The API endpoint to call
      * @param bucketId - The bucket ID
-     * @param folderId - The folder ID
      * @param path - The file path
+     * @param headers - Pre-built folder-context headers (built via `resolveFolderHeaders`)
      * @param queryOptions - Additional query parameters
      * @returns Promise resolving to blob file access information
      */
@@ -1071,11 +1184,11 @@ declare class BucketService extends FolderScopedService implements BucketService
     /**
      * Gets a direct upload URL for a file in the bucket
      *
-     * @param options - Contains bucketId, folderId, file path, optional expiry time
+     * @param options - Contains bucketId, file path, optional expiry time, and pre-built folder-context headers
      * @returns Promise resolving to blob file access information
      */
     private _getWriteUri;
 }
 
 export { BucketOptions, BucketService, BucketService as Buckets };
-export type { BlobItem, BucketDeleteFileOptions, BucketFile, BucketGetAllOptions, BucketGetByIdOptions, BucketGetByNameOptions, BucketGetFileMetaDataOptions, BucketGetFileMetaDataResponse, BucketGetFileMetaDataWithPaginationOptions, BucketGetFilesOptions, BucketGetReadUriOptions, BucketGetResponse, BucketGetUriOptions, BucketGetUriResponse, BucketServiceModel, BucketUploadFileOptions, BucketUploadResponse, ResponseDictionary };
+export type { BlobItem, BucketDeleteFileOptions, BucketFile, BucketGetAllOptions, BucketGetByIdOptions, BucketGetByNameOptions, BucketGetFileMetaDataOptions, BucketGetFileMetaDataResponse, BucketGetFileMetaDataWithPaginationOptions, BucketGetFilesOptions, BucketGetReadUriOptions, BucketGetReadUriRequestOptions, BucketGetResponse, BucketGetUriOptions, BucketGetUriResponse, BucketServiceModel, BucketUploadFileOptions, BucketUploadFileRequestOptions, BucketUploadResponse, ResponseDictionary };