amplify-libraries Flutter multibucket support documentation update (#8115)

* updated storage section for multibucket support

* updated api explanations for consistency

* removed section on passwordless since flutter doesnt support it yet

Author: ekjotmultani

src/pages/[platform]/build-a-backend/auth/modify-resources-with-cdk/index.mdx

@@ -117,6 +117,8 @@ cfnUserPool.enabledMfas = [...(cfnUserPool.enabledMfas || []), "EMAIL_OTP"]
 {/* BYO custom idp construct */}
 {/* extend auth/unauth roles */}
 
+<InlineFilter filters={["android","angular", "javascript", "nextjs", "react", "react-native", "swift", "vue"]}>
+
 ### Override Cognito UserPool to enable passwordless sign-in methods
 
 You can modify the underlying Cognito user pool resource to enable sign in with passwordless methods. [Learn more about passwordless sign-in methods](/[platform]/build-a-backend/auth/concepts/passwordless/).
@@ -146,3 +148,4 @@ cfnUserPoolClient.explicitAuthFlows = [
 cfnUserPool.addPropertyOverride('WebAuthnRelyingPartyID', '<RELYING_PARTY>');
 cfnUserPool.addPropertyOverride('WebAuthnUserVerification', 'preferred');
 ```
+</InlineFilter>

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

@@ -139,12 +139,48 @@ Future<void> copy() async {
   }
 }
 ```
+## Specify a bucket or copy across buckets / regions
 
-## More `copy` options
+You can also perform a `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:
 
@@ -156,6 +192,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

@@ -291,13 +291,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) {
@@ -681,7 +689,6 @@ const result = await downloadData({
 }).result;
 
 ```
-
 ### Monitor download progress
 
 ```javascript
@@ -717,7 +724,6 @@ try {
 ```
 
 </InlineFilter>
-
 <InlineFilter filters={["android"]}>
 
 ### Download from a specified bucket
@@ -1104,6 +1110,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 |
@@ -1119,6 +1126,7 @@ final operation = Amplify.Storage.downloadFile(
       getProperties: true,
       useAccelerateEndpoint: true,
     ),
+    bucket: StorageBucket.fromOutputs('secondBucket'),
   ),
 );
 ```
@@ -1138,6 +1146,42 @@ final operation = Amplify.Storage.downloadData(
 );
 ```
 
+You can also perform a `downloadData` or `downloadFile` operation to a specific bucket by providing the `bucket` option. You can pass in a `StorageBucket` object representing the target bucket from the name defined in the Amplify Backend.
+
+```dart
+final operation = Amplify.Storage.downloadFile(
+  path: const StoragePath.fromString('public/example.txt'),
+  localFile: AWSFile.fromPath('/path/to/local/file.txt'),
+  options: const StorageDownloadFileOptions(
+    pluginOptions: S3DownloadFilePluginOptions(
+      getProperties: true,
+      useAccelerateEndpoint: true,
+    ),
+    bucket: StorageBucket.fromOutputs('secondBucket'),
+  ),
+);
+```
+
+Alternatively, you can also pass in an object by specifying the bucket name and region from the console.
+
+```dart
+final operation = Amplify.Storage.downloadData(
+  path: const StoragePath.fromString('public/example.txt'),
+  options: StorageDownloadDataOptions(
+    pluginOptions: S3DownloadDataPluginOptions(
+      getProperties: true,
+      useAccelerateEndpoint: true,
+      bytesRange: S3DataBytesRange(start: 0, end: 100),
+    ),
+    bucket: StorageBucket.fromBucketInfo(
+      BucketInfo(
+        bucketName: 'second-bucket-name-from-console',
+        region: 'us-east-2',
+      ),
+    ),
+  ),
+);
+```
 </InlineFilter>
 
 <InlineFilter filters={["swift"]}>

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

@@ -1012,11 +1012,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 `StorageBucket` object representing the target bucket from the name defined in the 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. |
 
@@ -1095,6 +1131,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 to a specific bucket by providing the `bucket` option. You can pass in a `StorageBucket` object representing the target bucket from the name defined in the Amplify Backend.
 
 ```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.