updated storage section for multibucket support

Author: ekjotmultani

src/pages/[platform]/build-a-backend/storage/copy-files/index.mdx

@@ -128,12 +128,48 @@ Future<void> copy() async {
   }
 }
 ```
+## Specify a bucket or copy across buckets / regions
 
-## More `copy` options
+You can also perform an `copy` operation to a specific bucket by providing the `CopyBuckets` option. 
+This option is an object that takes two `StorageBucket` parameters, which can be constructed by the specified name in the Amplify Backend, or the bucket name and region from the console.
+
+```dart
+final mainBucket = StorageBucket.fromOutputs(
+  'mainBucket',
+);
+final bucket2 = StorageBucket.fromBucketInfo(
+  BucketInfo(
+    bucketName: 'second-bucket-name-from-console',
+    region: 'us-east-2',
+  ),
+),
+try {
+  final result = await Amplify.Storage.copy(
+    source: const StoragePath.fromString('album/2024/1.jpg'),
+    destination: const StoragePath.fromString('shared/2024/1.jpg'),
+    options: StorageCopyOptions(
+      buckets: CopyBuckets(
+        source: bucket1,
+        destination: bucket2,
+      ),
+    ),
+  ).result;
+  safePrint('Copied file: ${result.copiedItem.path}');
+} on StorageException catch (e) {
+  print('Error: $e');
+}
+```
+
+<Callout>
+In order to copy to or from a bucket other than your default, the source and/or destination paths must exist in that bucket
+</Callout>
+
+## `copy` options
 
 Option | Type | Description |
 | -- | -- | ----------- |
 | getProperties | boolean | Whether to retrieve properties for the copied object using theAmplify.Storage.getProperties() after the operation completes. When set to true the returned item will contain additional info such as metadata and content type. |
+| buckets | CopyBuckets | An object that accepts two `StorageBucket` parameters. To copy to and from the same bucket, use the `CopyBuckets.sameBucket(targetBucket)` method, where `targetBucket` is a `StorageBucket`. Read more at [Configure additional storage buckets](/[platform]/build-a-backend/storage/set-up-storage/#configure-additional-storage-buckets)|
 
 Example of `copy` with options:
 
@@ -145,6 +181,9 @@ final result = Amplify.Storage.copy(
     pluginOptions: S3CopyPluginOptions(
       getProperties: true,
     ),
+    buckets: CopyBuckets.sameBucket(
+      StorageBucket.fromOutputs('secondBucket'),
+    ),
   ),
 );
 ```

src/pages/[platform]/build-a-backend/storage/download-files/index.mdx

@@ -288,13 +288,21 @@ Option | Type | Description |
 When creating a downloadable URL, you can choose to check if the file exists by setting `validateObjectExistence` to
 `true` in `S3GetUrlPluginOptions`. If the file is inaccessible or does not exist, a `StorageException` is thrown.
 This allows you to check if an object exists during generating the presigned URL, which you can then use to download
-that object.
+that object. You may also pass in a bucket to target into `StorageGetUrlOptions` from either the chosen name in the 
+backend or the console name and region. If no bucket is provided, the default bucket defined in the backend will be used. 
+Read more at [Configure additional storage buckets](/[platform]/build-a-backend/storage/set-up-storage/#configure-additional-storage-buckets) 
 
 ```dart
 Future<void> getDownloadUrl() async {
   try {
     final result = await Amplify.Storage.getUrl(
       path: const StoragePath.fromString('public/example.txt'),
+      /* 
+      // targeting a specific bucket by the name defined in the backend 
+      options: StorageGetUrlOptions(
+        bucket: StorageBucket.fromOutputs('secondBucket'),
+      ),
+      */
     ).result;
     safePrint('url: ${result.url}');
   } on StorageException catch (e) {
@@ -678,7 +686,6 @@ const result = await downloadData({
 }).result;
 
 ```
-
 ### Monitor download progress
 
 ```javascript
@@ -714,7 +721,6 @@ try {
 ```
 
 </InlineFilter>
-
 <InlineFilter filters={["android"]}>
 
 ### Download from a specified bucket
@@ -1101,6 +1107,7 @@ Future<void> download() async {
 
 Option | Type | Description |
 | -- | -- | ----------- |
+| bucket | StorageBucket | The target bucket from the assigned name in the Amplify Backend or from the bucket name and region in the console<br/><br/>Defaults to the default bucket and region from the Amplify configuration if this option is not provided.<br/><br/>Read more at [Configure additional storage buckets](/[platform]/build-a-backend/storage/set-up-storage/#configure-additional-storage-buckets) |
 | getProperties | boolean | Whether to retrieve properties for the downloaded object using theAmplify.Storage.getProperties() after the operation completes. When set to true the returned item will contain additional info such as metadata and content type. |
 | useAccelerateEndpoint | boolean | Whether to use accelerate endpoint. <br/><br/> Read more at [Transfer Acceleration](/[platform]/build-a-backend/storage/upload-files/#transfer-acceleration) |
 | bytesRange | S3DataBytesRange | The byte range to download from the object |
@@ -1116,6 +1123,7 @@ final operation = Amplify.Storage.downloadFile(
       getProperties: true,
       useAccelerateEndpoint: true,
     ),
+    bucket: StorageBucket.fromOutputs('secondBucket'),
   ),
 );
 ```
@@ -1131,6 +1139,12 @@ final operation = Amplify.Storage.downloadData(
       useAccelerateEndpoint: true,
       bytesRange: S3DataBytesRange(start: 0, end: 100),
     ),
+    bucket: StorageBucket.fromBucketInfo(
+      BucketInfo(
+        bucketName: 'second-bucket-name-from-console',
+        region: 'us-east-2',
+      ),
+    ),
   ),
 );
 ```

src/pages/[platform]/build-a-backend/storage/list-files/index.mdx

@@ -1010,11 +1010,47 @@ Future<void> listAllUnderPublicPath() async {
 }
 
 ```
+<InlineFilter filters={["flutter"]}>
+
+### List files from a specified bucket
+You can also perform a `list` operation to a specific bucket by providing the `bucket` option. You can pass in a object representing the target bucket in Amplify Backend.
+
+```dart
+final result = await Amplify.Storage.list(
+  path: const StoragePath.fromString('path/to/dir'),
+  options: StorageListOptions(
+    // highlight-start
+    // Specify a target bucket using name assigned in Amplify Backend
+    bucket: StorageBucket.fromOutputs('secondBucket'),
+    // highlight-end
+  ),
+).result;
+```
+Alternatively, you can also pass in an object by specifying the bucket name and region from the console.
+
+```dart
+final result = await Amplify.Storage.list(
+  path: const StoragePath.fromString('path/to/dir'),
+  options: StorageListOptions(
+    // highlight-start
+    // Alternatively, provide bucket name from console and associated region
+   bucket: StorageBucket.fromBucketInfo(
+        BucketInfo(
+          bucketName: 'second-bucket-name-from-console',
+          region: 'us-east-2',
+        ),
+      ),
+      // highlight-end
+  ),
+).result;
+```
+</InlineFilter>
 
 ### More `list` options
 
 | Option | Type | Description |
 | --- | --- | --- |
+| bucket | StorageBucket | The target bucket from the assigned name in the Amplify Backend or from the bucket name and region in the console<br/><br/>Defaults to the default bucket and region from the Amplify configuration if this option is not provided.<br/><br/>Read more at [Configure additional storage buckets](/[platform]/build-a-backend/storage/set-up-storage/#configure-additional-storage-buckets) |
 | excludeSubPaths | boolean | Whether to exclude objects under the sub paths of the path to list. Defaults to false. |
 | delimiter | String | The delimiter to use when evaluating sub paths. If excludeSubPaths is false, this value has no impact on behavior. |
 
@@ -1093,6 +1129,35 @@ Future<void> getFileProperties() async {
 }
 ```
 
+As well as specify a bucket to target to view properties of a file
+
+```dart
+Future<void> getFileProperties() async {
+  try {
+    final result = await Amplify.Storage.getProperties(
+      path: const StoragePath.fromString('example.txt'),
+      options: StorageGetPropertiesOptions(
+        StorageBucket.fromOutputs('secondBucket'),
+      ),
+      // Alternatively, provide bucket name from console and associated region
+      /*
+      options: StorageGetPropertiesOptions( 
+        bucket: StorageBucket.fromBucketInfo(
+          BucketInfo(
+            bucketName: 'second-bucket-name-from-console',
+            region: 'us-east-2',
+          ),
+        ),
+      ),
+      */
+    ).result;
+    safePrint('File size: ${result.storageItem.size}');
+  } on StorageException catch (e) {
+    safePrint(e.message);
+  }
+}
+```
+
 <Callout>
 
 To get the metadata in result for all APIs when building against a web target, you have to configure user defined metadata in CORS.

src/pages/[platform]/build-a-backend/storage/remove-files/index.mdx

@@ -341,28 +341,42 @@ let removedObject = try await Amplify.Storage.remove(
 
 <InlineFilter filters={["flutter"]}>
 
-## Remove single file
-
-You can remove a single file using `Amplify.Storage.remove` with the `key` and its associated access level:
+You can also perform a remove operation from a specific bucket by providing the target bucket's assigned name from Amplify Backend in `bucket` option.
 
 ```dart
+final result = await Amplify.Storage.remove(
+  path: const StoragePath.fromString('path/to/file.txt'),
+  options: StorageRemoveOptions(
+    // highlight-start
+    // Specify a target bucket using name assigned in Amplify Backend
+    bucket: StorageBucket.fromOutputs('secondBucket'),
+    // highlight-end
+  ),
+).result;
+```
 
-Future<void> removeFile() async {
-  try {
-    final result = await Amplify.Storage.remove(
-      path: const StoragePath.fromString('public/file.txt'),
-    ).result;
-    safePrint('Removed file: ${result.removedItem.path}');
-  } on StorageException catch (e) {
-    safePrint(e.message);
-  }
-}
+Alternatively, you can also pass in an object by specifying the bucket name and region from the console.
 
+```dart
+final result = await Amplify.Storage.remove(
+  path: const StoragePath.fromString('path/to/file.txt'),
+  options: StorageRemoveOption(
+    // highlight-start
+    // Alternatively, provide bucket name from console and associated region
+   bucket: StorageBucket.fromBucketInfo(
+        BucketInfo(
+          bucketName: 'second-bucket-name-from-console',
+          region: 'us-east-2',
+        ),
+      ),
+      // highlight-end
+  ),
+).result;
 ```
 
 ## Remove multiple Files
 
-You can remove multiple files using `Amplify.Storage.removeMany` with the `keys`, the files to be removed in a batch should have the same access level:
+You can remove multiple files using `Amplify.Storage.removeMany`, as well as specify a bucket to target, the files to be removed in a batch should have the same access level:
 
 ```dart
 Future<void> remove() async {
@@ -372,6 +386,18 @@ Future<void> remove() async {
         const StoragePath.fromString('public/file-1.txt'),
         const StoragePath.fromString('public/file-2.txt'),
       ],
+      // if this option is not provided, the default bucket in the Amplify Backend will be used
+      options: StorageRemoveManyOptions(
+        bucket: StorageBucket.fromOutputs('secondBucket'),
+        /* Alternatively, provide bucket name from console and associated region
+        bucket: StorageBucket.fromBucketInfo(
+          BucketInfo(
+            bucketName: 'second-bucket-name-from-console',
+            region: 'us-east-2',
+          ),
+        ),
+        */
+      ),
     ).result;
     safePrint('Removed files: ${result.removedItems}');
   } on StorageException catch (e) {

src/pages/[platform]/build-a-backend/storage/set-up-storage/index.mdx

@@ -363,6 +363,54 @@ let downloadTask = Amplify.Storage.downloadData(
 ```
 </InlineFilter>
 
+<InlineFilter filters={["flutter"]}>
+### Storage bucket client usage
+
+Additional storage buckets can be referenced from application code by passing the `bucket` option to Amplify Storage APIs. You can provide a target bucket's name assigned in Amplify Backend.
+
+```dart
+import 'package:amplify_flutter/amplify_flutter.dart';
+
+try {
+  final result = await Amplify.Storage.downloadData(
+    path: const StoragePath.fromString('album/2024/1.jpg'),
+    options: StorageDownloadDataOptions(
+      // highlight-start
+      // Specify a target bucket using name assigned in Amplify Backend
+      bucket: StorageBucket.fromOutputs('secondBucket'),
+      // highlight-end
+    ),
+  ).result;
+} on Exception catch (e) {
+    print('Error: $e');
+}
+```
+Alternatively, you can also pass in an object by specifying the bucket name and region from the console. See each Amplify Storage API page for additional usage examples.
+
+```dart
+import 'package:amplify_flutter/amplify_flutter.dart';
+
+try {
+  final result = await Amplify.Storage.downloadData(
+    path: const StoragePath.fromString('album/2024/1.jpg'),
+    options: const StorageDownloadDataOptions(
+      // highlight-start
+      // Alternatively, provide bucket name from console and associated region
+      bucket: StorageBucket.fromBucketInfo(
+        BucketInfo(
+          bucketName: 'second-bucket-name-from-console',
+          region: 'us-east-2',
+        ),
+      ),
+      // highlight-end
+    ),
+  ).result;
+} on Exception catch (e) {
+  print('Error: $e');
+}
+```
+</InlineFilter>
+
 ## Connect your app code to the storage backend
 
 The Amplify Storage library provides client APIs that connect to the backend resources you defined.

src/pages/[platform]/build-a-backend/storage/upload-files/index.mdx

@@ -647,10 +647,52 @@ Future<void> upload() async {
 
 <InlineFilter filters={["flutter"]}>
 
+### Upload to a specified bucket
+
+You can also perform an `upload` operation to a specific bucket by providing the `bucket` option. You can pass in an object representing the target bucket in Amplify Backend.
+
+```dart
+final data = 'multi bucket upload data byte'.codeUnits;
+final result = await Amplify.Storage.uploadData(
+  data: StorageDataPayload.bytes(data),
+  path: const StoragePath.fromString('path/to/file.txt'),
+  options: StorageUploadDataOptions(
+    // highlight-start
+    // Specify a target bucket using name assigned in Amplify Backend
+    bucket: StorageBucket.fromOutputs('secondBucket'),
+    // highlight-end
+  ),
+).result;
+```
+Alternatively, you can also pass in an object by specifying the bucket name and region from the console.
+
+```dart
+final data = 'multi bucket upload data byte'.codeUnits;
+final result = await Amplify.Storage.uploadData(
+  data: StorageDataPayload.bytes(data),
+  path: const StoragePath.fromString('path/to/file.txt'),
+  options: StorageUploadDataOptions(
+    // highlight-start
+    // Alternatively, provide bucket name from console and associated region
+   bucket: StorageBucket.fromBucketInfo(
+        BucketInfo(
+          bucketName: 'second-bucket-name-from-console',
+          region: 'us-east-2',
+        ),
+      ),
+      // highlight-end
+  ),
+).result;
+```
+</InlineFilter>
+
+<InlineFilter filters={["flutter"]}>
+
 ### More upload options
 
 Option | Type | Description |
 | -- | -- | ----------- |
+| bucket | StorageBucket | The target bucket from the assigned name in the Amplify Backend or from the bucket name and region in the console<br/><br/>Defaults to default bucket and region from the Amplify configuration if this option is not provided.<br/><br/>Read more at [Configure additional storage buckets](/[platform]/build-a-backend/storage/set-up-storage/#configure-additional-storage-buckets) |
 | getProperties | boolean | Whether to retrieve properties for the uploaded object using theAmplify.Storage.getProperties() after the operation completes. When set to true the returned item will contain additional info such as metadata and content type. |
 | useAccelerateEndpoint | boolean | Whether to use accelerate endpoint. <br/><br/> Read more at [Transfer Acceleration](/[platform]/build-a-backend/storage/upload-files/#transfer-acceleration) |