chore: kickoff release

Author: phantumcode

Amplify/Categories/Storage/Operation/Request/StorageListRequest.swift

@@ -5,39 +5,84 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// - Tag: StorageListRequest
 public struct StorageListRequest: AmplifyOperationRequest {
+
     /// Options to adjust the behavior of this request, including plugin-options
+    /// - Tag: StorageListRequest
     public let options: Options
 
+    /// - Tag: StorageListRequest.init
     public init(options: Options) {
         self.options = options
     }
 }
 
 public extension StorageListRequest {
-    /// Options to adjust the behavior of this request, including plugin-options
+
+    /// Options available to callers of
+    /// [StorageCategoryBehavior.list](x-source-tag://StorageCategoryBehavior.list).
+    ///
+    /// Tag: StorageListRequestOptions
     struct Options {
+
         /// Access level of the storage system. Defaults to `public`
+        ///
+        /// - Tag: StorageListRequestOptions.accessLevel
         public let accessLevel: StorageAccessLevel
 
         /// Target user to apply the action on
+        ///
+        /// - Tag: StorageListRequestOptions.targetIdentityId
         public let targetIdentityId: String?
 
         /// Path to the keys
+        ///
+        /// - Tag: StorageListRequestOptions.path
         public let path: String?
 
+        /// Number between 1 and 1,000 that indicates the limit of how many entries to fetch when
+        /// retreiving file lists from the server.
+        ///
+        /// NOTE: Plugins may decide to throw or perform normalization when encoutering vaues outside
+        ///       the specified range.
+        ///
+        /// - SeeAlso:
+        /// [StorageListRequestOptions.nextToken](x-source-tag://StorageListRequestOptions.nextToken)
+        /// [StorageListResult.nextToken](x-source-tag://StorageListResult.nextToken)
+        ///
+        /// - Tag: StorageListRequestOptions.pageSize
+        public let pageSize: UInt
+
+        /// Opaque string indicating the page offset at which to resume a listing. This is usually a copy of
+        /// the value from [StorageListResult.nextToken](x-source-tag://StorageListResult.nextToken).
+        ///
+        /// - SeeAlso:
+        /// [StorageListRequestOptions.pageSize](x-source-tag://StorageListRequestOptions.pageSize)
+        /// [StorageListResult.nextToken](x-source-tag://StorageListResult.nextToken)
+        ///
+        /// - Tag: StorageListRequestOptions.nextToken
+        public let nextToken: String?
+
         /// Extra plugin specific options, only used in special circumstances when the existing options do not provide
         /// a way to utilize the underlying storage system's functionality. See plugin documentation for expected
         /// key/values
+        ///
+        /// - Tag: StorageListRequestOptions.pluginOptions
         public let pluginOptions: Any?
 
+        /// - Tag: StorageListRequestOptions.init
         public init(accessLevel: StorageAccessLevel = .guest,
                     targetIdentityId: String? = nil,
                     path: String? = nil,
+                    pageSize: UInt = 1000,
+                    nextToken: String? = nil,
                     pluginOptions: Any? = nil) {
             self.accessLevel = accessLevel
             self.targetIdentityId = targetIdentityId
             self.path = path
+            self.pageSize = pageSize
+            self.nextToken = nextToken
             self.pluginOptions = pluginOptions
         }
     }

Amplify/Categories/Storage/Result/StorageListResult.swift

@@ -7,35 +7,71 @@
 
 import Foundation
 
+/// Represents the output of a call to
+/// [StorageCategoryBehavior.list](x-source-tag://StorageCategoryBehavior.list)
+///
+/// - Tag: StorageListResult
 public struct StorageListResult {
-    public init(items: [Item]) {
+
+    /// This is meant to be called by plugins implementing
+    /// [StorageCategoryBehavior.list](x-source-tag://StorageCategoryBehavior.list).
+    ///
+    /// - Tag: StorageListResult.init
+    public init(items: [Item], nextToken: String? = nil) {
         self.items = items
+        self.nextToken = nextToken
     }
 
-    // Array of Items in the Result
+    /// Array of Items in the Result
+    ///
+    /// - Tag: StorageListResult.items
     public var items: [Item]
+
+    /// Opaque string indicating the page offset at which to resume a listing. This value is usually copied to
+    /// [StorageListRequestOptions.nextToken](x-source-tag://StorageListRequestOptions.nextToken).
+    ///
+    /// - SeeAlso:
+    /// [StorageListRequestOptions.nextToken](x-source-tag://StorageListRequestOptions.nextToken)
+    ///
+    /// - Tag: StorageListResult.nextToken
+    public let nextToken: String?
 }
 
 extension StorageListResult {
 
+    /// - Tag: StorageListResultItem
     public struct Item {
 
         /// The unique identifier of the object in storage.
+        ///
+        /// - Tag: StorageListResultItem.key
         public let key: String
 
         /// Size in bytes of the object
+        ///
+        /// - Tag: StorageListResultItem.size
         public let size: Int?
 
         /// The date the Object was Last Modified
+        ///
+        /// - Tag: StorageListResultItem.lastModified
         public let lastModified: Date?
 
         /// The entity tag is an MD5 hash of the object.
         /// ETag reflects only changes to the contents of an object, not its metadata.
+        ///
+        /// - Tag: StorageListResultItem.eTag
         public let eTag: String?
 
         /// Additional results specific to the plugin.
+        ///
+        /// - Tag: StorageListResultItem.pluginResults
         public let pluginResults: Any?
 
+        /// This is meant to be called by plugins implementing
+        /// [StorageCategoryBehavior.list](x-source-tag://StorageCategoryBehavior.list).
+        ///
+        /// - Tag: StorageListResultItem.init
         public init(key: String,
                     size: Int? = nil,
                     eTag: String? = nil,

Amplify/Categories/Storage/StorageCategoryBehavior.swift

@@ -7,7 +7,11 @@
 
 import Foundation
 
-/// Behavior of the Storage category that clients will use
+/// Behavior of the Storage category used though `Amplify.Storage.*`. Plugin implementations
+/// conform to this protocol indirectly though the
+/// [StorageCategoryPlugin](x-source-tag://StorageCategoryPlugin) protocol.
+///
+/// - Tag: StorageCategoryBehavior
 public protocol StorageCategoryBehavior {
 
     /// Retrieve the remote URL for the object from storage.
@@ -16,6 +20,8 @@ public protocol StorageCategoryBehavior {
     ///   - key: The unique identifier for the object in storage.
     ///   - options: Parameters to specific plugin behavior
     /// - Returns: requested Get URL
+    ///
+    /// - Tag: StorageCategoryBehavior.getURL
     @discardableResult
     func getURL(key: String,
                 options: StorageGetURLOperation.Request.Options?) async throws -> URL
@@ -26,6 +32,8 @@ public protocol StorageCategoryBehavior {
     ///   - key: The unique identifier for the object in storage
     ///   - options: Options to adjust the behavior of this request, including plugin-options
     /// - Returns: A task that provides progress updates and the key which was used to download
+    ///
+    /// - Tag: StorageCategoryBehavior.downloadData
     @discardableResult
     func downloadData(key: String,
                       options: StorageDownloadDataOperation.Request.Options?) -> StorageDownloadDataTask
@@ -37,6 +45,8 @@ public protocol StorageCategoryBehavior {
     ///   - local: The local file to download destination
     ///   - options: Parameters to specific plugin behavior
     /// - Returns: A task that provides progress updates and the key which was used to download
+    ///
+    /// - Tag: StorageCategoryBehavior.downloadFile
     @discardableResult
     func downloadFile(key: String,
                       local: URL,
@@ -49,6 +59,8 @@ public protocol StorageCategoryBehavior {
     ///   - data: The data in memory to be uploaded
     ///   - options: Parameters to specific plugin behavior
     /// - Returns: A task that provides progress updates and the key which was used to upload
+    ///
+    /// - Tag: StorageCategoryBehavior.uploadData
     @discardableResult
     func uploadData(key: String,
                     data: Data,
@@ -61,6 +73,8 @@ public protocol StorageCategoryBehavior {
     ///   - local: The path to a local file.
     ///   - options: Parameters to specific plugin behavior
     /// - Returns: A task that provides progress updates and the key which was used to upload
+    ///
+    /// - Tag: StorageCategoryBehavior.uploadFile
     @discardableResult
     func uploadFile(key: String,
                     local: URL,
@@ -72,6 +86,8 @@ public protocol StorageCategoryBehavior {
     ///   - key: The unique identifier of the object in storage.
     ///   - options: Parameters to specific plugin behavior
     /// - Returns: An operation object that provides notifications and actions related to the execution of the work
+    ///
+    /// - Tag: StorageCategoryBehavior.remove
     @discardableResult
     func remove(key: String,
                 options: StorageRemoveOperation.Request.Options?) async throws -> String
@@ -82,12 +98,16 @@ public protocol StorageCategoryBehavior {
     ///   - options: Parameters to specific plugin behavior
     ///   - resultListener: Triggered when the list is complete
     /// - Returns: An operation object that provides notifications and actions related to the execution of the work
+    ///
+    /// - Tag: StorageCategoryBehavior.list
     @discardableResult
     func list(options: StorageListOperation.Request.Options?) async throws -> StorageListResult
 
     /// Handles background events which are related to URLSession
     /// - Parameter identifier: identifier
     /// - Returns: returns true if the identifier is handled by Amplify
+    ///
+    /// - Tag: StorageCategoryBehavior.handleBackgroundEvents
     func handleBackgroundEvents(identifier: String) async -> Bool
 
 }

Amplify/Categories/Storage/StorageCategoryPlugin.swift

@@ -5,6 +5,7 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// - Tag: StorageCategoryPlugin
 public protocol StorageCategoryPlugin: Plugin, StorageCategoryBehavior { }
 
 public extension StorageCategoryPlugin {

AmplifyPlugins/Auth/Sources/AWSCognitoAuthPlugin/Actions/SignIn/DeviceSRPAuth/InitiateAuthDeviceSRP.swift

@@ -33,6 +33,10 @@ struct InitiateAuthDeviceSRP: Action {
                 for: username,
                 with: environment)
 
+            let asfDeviceId = try await CognitoUserPoolASF.asfDeviceID(
+                for: username,
+                credentialStoreClient: environment.authEnvironment().credentialsClient)
+
             let srpStateData = SRPStateData(
                 username: username,
                 password: "",
@@ -45,6 +49,7 @@ struct InitiateAuthDeviceSRP: Action {
                 username: username,
                 environment: userPoolEnv,
                 deviceMetadata: deviceMetadata,
+                asfDeviceId: asfDeviceId,
                 session: authResponse.session,
                 publicHexValue: srpKeyPair.publicKeyHexValue)
 

AmplifyPlugins/Auth/Sources/AWSCognitoAuthPlugin/Actions/SignIn/DeviceSRPAuth/VerifyDevicePasswordSRP.swift

@@ -33,6 +33,10 @@ struct VerifyDevicePasswordSRP: Action {
             let secretBlock = try secretBlock(secretBlockString)
             let serverPublicB = try serverPublic(parameters)
 
+            let asfDeviceId = try await CognitoUserPoolASF.asfDeviceID(
+                for: username,
+                credentialStoreClient: environment.authEnvironment().credentialsClient)
+
             let deviceMetadata = await DeviceMetadataHelper.getDeviceMetadata(
                 for: username,
                 with: environment)
@@ -62,6 +66,7 @@ struct VerifyDevicePasswordSRP: Action {
                 secretBlock: secretBlockString,
                 signature: signature,
                 deviceMetadata: deviceMetadata,
+                asfDeviceId: asfDeviceId,
                 environment: userPoolEnv)
 
             let responseEvent = try await UserPoolSignInHelper.sendRespondToAuth(

AmplifyPlugins/Auth/Sources/AWSCognitoAuthPlugin/Actions/SignIn/SRPAuth/VerifyPasswordSRP.swift

@@ -41,6 +41,10 @@ struct VerifyPasswordSRP: Action {
             let secretBlock = try secretBlock(secretBlockString)
             let serverPublicB = try serverPublic(parameters)
 
+            let asfDeviceId = try await CognitoUserPoolASF.asfDeviceID(
+                for: username,
+                credentialStoreClient: environment.authEnvironment().credentialsClient)
+
             deviceMetadata = await DeviceMetadataHelper.getDeviceMetadata(
                 for: username,
                 with: environment)
@@ -57,6 +61,7 @@ struct VerifyPasswordSRP: Action {
                 secretBlock: secretBlockString,
                 signature: signature,
                 deviceMetadata: deviceMetadata,
+                asfDeviceId: asfDeviceId,
                 environment: userPoolEnv)
             let responseEvent = try await UserPoolSignInHelper.sendRespondToAuth(
                 request: request,

AmplifyPlugins/Auth/Sources/AWSCognitoAuthPlugin/Actions/SignIn/VerifySignInChallenge.swift

@@ -31,6 +31,10 @@ struct VerifySignInChallenge: Action {
             let challengeType = challenge.challenge
             let responseKey = try challenge.getChallengeKey()
 
+            let asfDeviceId = try await CognitoUserPoolASF.asfDeviceID(
+                for: username,
+                credentialStoreClient: environment.authEnvironment().credentialsClient)
+
             deviceMetadata = await DeviceMetadataHelper.getDeviceMetadata(
                             for: username,
                             with: environment)
@@ -42,6 +46,7 @@ struct VerifySignInChallenge: Action {
                 responseKey: responseKey,
                 answer: confirmSignEventData.answer,
                 clientMetadata: confirmSignEventData.metadata,
+                asfDeviceId: asfDeviceId,
                 attributes: confirmSignEventData.attributes,
                 deviceMetadata: deviceMetadata,
                 environment: userpoolEnv)

AmplifyPlugins/Auth/Sources/AWSCognitoAuthPlugin/Support/Utils/ConfirmSignUpInput+Amplify.swift

@@ -12,7 +12,7 @@ extension ConfirmSignUpInput {
     init(username: String,
          confirmationCode: String,
          clientMetadata: [String: String]?,
-         asfDeviceId: String? = nil,
+         asfDeviceId: String?,
          environment: UserPoolEnvironment
     ) {
 
@@ -38,6 +38,7 @@ extension ConfirmSignUpInput {
             clientMetadata: clientMetadata,
             confirmationCode: confirmationCode,
             secretHash: secretHash,
-            userContextData: userContextData, username: username)
+            userContextData: userContextData,
+            username: username)
     }
 }

AmplifyPlugins/Auth/Sources/AWSCognitoAuthPlugin/Support/Utils/InitiateAuthInput+Amplify.swift

@@ -100,7 +100,7 @@ extension InitiateAuthInput {
                            authFlowType: CognitoIdentityProviderClientTypes.AuthFlowType,
                            authParameters: [String: String],
                            clientMetadata: [String: String],
-                           asfDeviceId: String? = nil,
+                           asfDeviceId: String?,
                            deviceMetadata: DeviceMetadata,
                            environment: UserPoolEnvironment) -> InitiateAuthInput {