feat!: Update storage APIs to accept StoragePath

canaries/integration_test/main_test.dart

@@ -30,14 +30,14 @@ void main() {
   IntegrationTestWidgetsFlutterBinding.ensureInitialized();
 
   const data = 'hello, world';
-  const dataKey = 'hello';
+  const path = StoragePath.fromString('public/hello');
   final event = AnalyticsEvent('hello');
 
   Future<void> performUnauthenticatedActions() async {
     // Upload data to Storage
     await Amplify.Storage.uploadData(
       data: HttpPayload.string(data),
-      key: dataKey,
+      path: path,
     ).result;
 
     // Record Analytics event
@@ -63,19 +63,15 @@ void main() {
   Future<void> performAuthenticatedActions() async {
     // Retrieve guest data
     final guestData = await Amplify.Storage.downloadData(
-      key: dataKey,
-      options: const StorageDownloadDataOptions(
-        accessLevel: StorageAccessLevel.guest,
-      ),
+      path: path,
     ).result;
     expect(utf8.decode(guestData.bytes), data);
 
     // Upload data to Storage
     await Amplify.Storage.uploadData(
       data: HttpPayload.string(data),
-      key: dataKey,
-      options: const StorageUploadDataOptions(
-        accessLevel: StorageAccessLevel.private,
+      path: StoragePath.fromIdentityId(
+        (String identityId) => 'private/$identityId/hello',
       ),
     ).result;
 

packages/amplify_core/lib/src/category/amplify_storage_category.dart

@@ -9,9 +9,6 @@ part of 'amplify_categories.dart';
 ///
 /// It comes with default, built-in support for Amazon S3 service
 /// leveraging Amplify Auth Category for authorization.
-///
-/// The Amplify CLI helps you to create and configure the storage category
-/// and auth category.
 /// {@endtemplate}
 class StorageCategory extends AmplifyCategory<StoragePluginInterface> {
   @override
@@ -37,7 +34,7 @@ class StorageCategory extends AmplifyCategory<StoragePluginInterface> {
   /// returns a [StorageListOperation].
   /// {@endtemplate}
   StorageListOperation list({
-    String? path,
+    required StoragePath path,
     StorageListOptions? options,
   }) {
     return identifyCall(
@@ -50,84 +47,84 @@ class StorageCategory extends AmplifyCategory<StoragePluginInterface> {
   }
 
   /// {@template amplify_core.amplify_storage_category.get_properties}
-  /// Retrieves properties of the object specified by [key] with optional
+  /// Retrieves properties of the object specified by [path] with optional
   /// [StorageGetPropertiesOptions]. And returns a
   /// [StorageGetPropertiesOperation].
   ///
   /// The result may include the metadata (if any) specified when the object
   /// was uploaded.
   /// {@endtemplate}
   StorageGetPropertiesOperation getProperties({
-    required String key,
+    required StoragePath path,
     StorageGetPropertiesOptions? options,
   }) {
     return identifyCall(
       StorageCategoryMethod.getProperties,
       () => defaultPlugin.getProperties(
-        key: key,
+        path: path,
         options: options,
       ),
     );
   }
 
   /// {@template amplify_core.amplify_storage_category.get_url}
-  /// Generates a downloadable url for the object specified by [key] with
+  /// Generates a downloadable url for the object specified by [path] with
   /// [StorageGetUrlOptions], and returns a [StorageGetUrlOperation].
   ///
   /// The url is presigned by the aws_signature_v4, and is enforced with scheme
   /// `https`.
   /// {@endtemplate}
   StorageGetUrlOperation getUrl({
-    required String key,
+    required StoragePath path,
     StorageGetUrlOptions? options,
   }) {
     return identifyCall(
       StorageCategoryMethod.getUrl,
       () => defaultPlugin.getUrl(
-        key: key,
+        path: path,
         options: options,
       ),
     );
   }
 
   /// {@template amplify_core.amplify_storage_category.download_data}
-  /// Downloads bytes of object specified by [key] into memory with optional
+  /// Downloads bytes of object specified by [path] into memory with optional
   /// [onProgress] and [StorageDownloadDataOptions], and returns a
   /// [StorageDownloadDataOperation].
   ///
   /// Ensure you are managing the data in memory properly to avoid unexpected
   /// memory leaks.
   /// {@endtemplate}
   StorageDownloadDataOperation downloadData({
-    required String key,
+    required StoragePath path,
     void Function(StorageTransferProgress)? onProgress,
     StorageDownloadDataOptions? options,
   }) {
     return identifyCall(
       StorageCategoryMethod.downloadData,
       () => defaultPlugin.downloadData(
-        key: key,
+        path: path,
         onProgress: onProgress,
         options: options,
       ),
     );
   }
 
   /// {@template amplify_core.amplify_storage_category.download_file}
-  /// Downloads the object specified by [key] to [localFile] with optional
+  /// Downloads the object specified by [path] to [localFile] with optional
   /// [onProgress] and [StorageDownloadFileOptions], and returns a
   /// [StorageDownloadFileOperation].
   /// {@endtemplate}
   StorageDownloadFileOperation downloadFile({
-    required String key,
+    required StoragePath path,
     required AWSFile localFile,
     void Function(StorageTransferProgress)? onProgress,
     StorageDownloadFileOptions? options,
   }) {
     return identifyCall(
       StorageCategoryMethod.downloadFile,
       () => defaultPlugin.downloadFile(
-        key: key,
+        path: path,
         localFile: localFile,
         onProgress: onProgress,
         options: options,
@@ -137,21 +134,21 @@ class StorageCategory extends AmplifyCategory<StoragePluginInterface> {
 
   /// {@template amplify_core.amplify_storage_category.upload_data}
   /// Uploads [data] as a [StorageDataPayload] with optional
-  /// [onProgress] and [StorageUploadDataOptions] to object specified by [key],
+  /// [onProgress] and [StorageUploadDataOptions] to object specified by [path],
   /// and returns a [StorageUploadDataOperation].
   ///
   /// See [StorageDataPayload] for supported data formats.
   /// {@endtemplate}
   StorageUploadDataOperation uploadData({
     required StorageDataPayload data,
-    required String key,
+    required StoragePath path,
     void Function(StorageTransferProgress)? onProgress,
     StorageUploadDataOptions? options,
   }) {
     return identifyCall(
       StorageCategoryMethod.uploadData,
       () => defaultPlugin.uploadData(
-        key: key,
+        path: path,
         data: data,
         onProgress: onProgress,
         options: options,
@@ -161,22 +158,22 @@ class StorageCategory extends AmplifyCategory<StoragePluginInterface> {
 
   /// {@template amplify_core.amplify_storage_category.upload_file}
   /// Uploads data from [localFile] with optional [onProgress] and
-  /// [StorageUploadFileOptions] to object specified by [key], and returns a
+  /// [StorageUploadFileOptions] to object specified by [path], and returns a
   /// [StorageUploadFileOperation].
   ///
   /// [AWSFile] provides various adapters to read file content from file
   /// abstractions, such as `XFile`, `PlatformFile`, `io.File` or `html.File`.
   /// {@endtemplate}
   StorageUploadFileOperation uploadFile({
     required AWSFile localFile,
-    required String key,
+    required StoragePath path,
     void Function(StorageTransferProgress)? onProgress,
     StorageUploadFileOptions? options,
   }) {
     return identifyCall(
       StorageCategoryMethod.uploadFile,
       () => defaultPlugin.uploadFile(
-        key: key,
+        path: path,
         localFile: localFile,
         onProgress: onProgress,
         options: options,
@@ -190,12 +187,11 @@ class StorageCategory extends AmplifyCategory<StoragePluginInterface> {
   /// {@endtemplate}
   ///
   /// {@template amplify_core.amplify_storage_category.copy_source}
-  /// The `source` should be readable to the API call originator following
-  /// corresponding [StorageAccessLevel].
+  /// The `source` should be readable to the API call originator.
   /// {@endtemplate}
   StorageCopyOperation copy({
-    required StorageItemWithAccessLevel<StorageItem> source,
-    required StorageItemWithAccessLevel<StorageItem> destination,
+    required StoragePath source,
+    required StoragePath destination,
     StorageCopyOptions? options,
   }) {
     return identifyCall(
@@ -208,65 +204,32 @@ class StorageCategory extends AmplifyCategory<StoragePluginInterface> {
     );
   }
 
-  /// {@template amplify_core.amplify_storage_category.move}
-  /// Moves [source] to [destination] with optional [StorageMoveOptions],
-  /// and returns a [StorageMoveOperation].
-  ///
-  /// This API performs two consecutive S3 service calls:
-  ///   1. copy the source object to destination objection
-  ///   2. delete the source object
-  ///
-  /// {@macro amplify_core.amplify_storage_category.copy_source}
-  /// {@endtemplate}
-  @Deprecated(
-    'This API will be removed in the next major version. '
-    'This API calls Amplify.Storage.copy() to create a copy of the file in the '
-    'destination directory and then calls Amplify.Storage.remove() to remove '
-    'the source file. '
-    'Please use Amplify.Storage.copy() and Amplify.Storage.remove() directly '
-    'instead.',
-  )
-  StorageMoveOperation move({
-    required StorageItemWithAccessLevel<StorageItem> source,
-    required StorageItemWithAccessLevel<StorageItem> destination,
-    StorageMoveOptions? options,
-  }) {
-    return identifyCall(
-      StorageCategoryMethod.move,
-      () => defaultPlugin.move(
-        source: source,
-        destination: destination,
-        options: options,
-      ),
-    );
-  }
-
   /// {@template amplify_core.amplify_storage_category.remove}
-  /// Removes an object specified by [key] with optional [StorageRemoveOptions],
+  /// Removes an object specified by [path] with optional [StorageRemoveOptions],
   /// and returns a [StorageRemoveOperation].
   /// {@endtemplate}
   StorageRemoveOperation remove({
-    required String key,
+    required StoragePath path,
     StorageRemoveOptions? options,
   }) {
     return identifyCall(
       StorageCategoryMethod.remove,
-      () => defaultPlugin.remove(key: key, options: options),
+      () => defaultPlugin.remove(path: path, options: options),
     );
   }
 
   /// {@template amplify_core.amplify_storage_category.remove_many}
-  /// Removes multiple objects specified by [keys] with optional
+  /// Removes multiple objects specified by [paths] with optional
   /// [StorageRemoveManyOptions], and returns a [StorageRemoveManyOperation].
   /// {@endtemplate}
   StorageRemoveManyOperation removeMany({
-    required List<String> keys,
+    required List<StoragePath> paths,
     StorageRemoveManyOptions? options,
   }) {
     return identifyCall(
       StorageCategoryMethod.removeMany,
       () => defaultPlugin.removeMany(
-        keys: keys,
+        paths: paths,
         options: options,
       ),
     );

packages/amplify_core/lib/src/plugin/amplify_storage_plugin_interface.dart

@@ -16,31 +16,31 @@ abstract class StoragePluginInterface extends AmplifyPluginInterface {
 
   /// {@macro amplify_core.amplify_storage_category.list}
   StorageListOperation list({
-    String? path,
+    required StoragePath path,
     StorageListOptions? options,
   }) {
     throw UnimplementedError('list() has not been implemented.');
   }
 
   /// {@macro amplify_core.amplify_storage_category.get_properties}
   StorageGetPropertiesOperation getProperties({
-    required String key,
+    required StoragePath path,
     StorageGetPropertiesOptions? options,
   }) {
     throw UnimplementedError('getProperties() has not been implemented.');
   }
 
   /// {@macro amplify_core.amplify_storage_category.get_url}
   StorageGetUrlOperation getUrl({
-    required String key,
+    required StoragePath path,
     StorageGetUrlOptions? options,
   }) {
     throw UnimplementedError('getUrl() has not been implemented.');
   }
 
   /// {@macro amplify_core.amplify_storage_category.download_data}
   StorageDownloadDataOperation downloadData({
-    required String key,
+    required StoragePath path,
     void Function(StorageTransferProgress)? onProgress,
     StorageDownloadDataOptions? options,
   }) {
@@ -49,7 +49,7 @@ abstract class StoragePluginInterface extends AmplifyPluginInterface {
 
   /// {@macro amplify_core.amplify_storage_category.download_file}
   StorageDownloadFileOperation downloadFile({
-    required String key,
+    required StoragePath path,
     required AWSFile localFile,
     void Function(StorageTransferProgress)? onProgress,
     StorageDownloadFileOptions? options,
@@ -59,7 +59,7 @@ abstract class StoragePluginInterface extends AmplifyPluginInterface {
 
   /// {@macro amplify_core.amplify_storage_category.upload_data}
   StorageUploadDataOperation uploadData({
-    required String key,
+    required StoragePath path,
     required StorageDataPayload data,
     void Function(StorageTransferProgress)? onProgress,
     StorageUploadDataOptions? options,
@@ -69,7 +69,7 @@ abstract class StoragePluginInterface extends AmplifyPluginInterface {
 
   /// {@macro amplify_core.amplify_storage_category.upload_file}
   StorageUploadFileOperation uploadFile({
-    required String key,
+    required StoragePath path,
     required AWSFile localFile,
     void Function(StorageTransferProgress)? onProgress,
     StorageUploadFileOptions? options,
@@ -79,33 +79,24 @@ abstract class StoragePluginInterface extends AmplifyPluginInterface {
 
   /// {@macro amplify_core.amplify_storage_category.copy}
   StorageCopyOperation copy({
-    required StorageItemWithAccessLevel<StorageItem> source,
-    required StorageItemWithAccessLevel<StorageItem> destination,
+    required StoragePath source,
+    required StoragePath destination,
     StorageCopyOptions? options,
   }) {
     throw UnimplementedError('copy() has not been implemented.');
   }
 
-  /// {@macro amplify_core.amplify_storage_category.move}
-  StorageMoveOperation move({
-    required StorageItemWithAccessLevel<StorageItem> source,
-    required StorageItemWithAccessLevel<StorageItem> destination,
-    StorageMoveOptions? options,
-  }) {
-    throw UnimplementedError('move() has not been implemented.');
-  }
-
   /// {@macro amplify_core.amplify_storage_category.remove}
   StorageRemoveOperation remove({
-    required String key,
+    required StoragePath path,
     StorageRemoveOptions? options,
   }) {
     throw UnimplementedError('remove() has not been implemented.');
   }
 
   /// {@macro amplify_core.amplify_storage_category.remove_many}
   StorageRemoveManyOperation removeMany({
-    required List<String> keys,
+    required List<StoragePath> paths,
     StorageRemoveManyOptions? options,
   }) {
     throw UnimplementedError('removeMany() has not been implemented.');