Merge pull request #969 from Web3Auth/sfa-ios-9

[SFA iOS] Update the docs for latest v9.0.x

docs/migration-guides/sfa-ios-v8-to-v9.mdx

@@ -0,0 +1,162 @@
+---
+title: SFA iOS SDK - v8 to v9
+description: "SFA iOS SDK - v8 to v9 | Documentation - Web3Auth"
+sidebar_label: v8 to v9
+---
+
+This migration guide provides steps for upgrading from version v8 to v9 of the SFA iOS SDK. The
+guide outlines significant changes and enhancements.
+
+## Breaking Changes
+
+### Web3AuthNetwork Changes
+
+In v9, we have removed the nested enum and refactored the Web3AuthNetwork. Please checkout the table
+below for the changes.
+
+| Old Value                    | New Value         |
+| ---------------------------- | ----------------- |
+| .sapphire(.SAPPHIRE_MAINNET) | .SAPPHIRE_MAINNET |
+| .sapphire(.SAPPHIRE_DEVNET)  | .SAPPHIRE_DEVNET  |
+| .legacy(.MAINNET)            | .MAINNET          |
+| .legacy(.TESTNET)            | .TESTNET          |
+| .legacy(.CYAN)               | .CYAN             |
+| .legacy(.AQUA)               | .AQUA             |
+
+### SFAParams Changes
+
+In v9, we try to improve the developer experience by renaming the `SFAParams` to `Web3AuthOptions`.
+It has been renamed to align with naming conventions across Web3Auth SDKs. Along with this, we have
+renamed couple of constructor parameters.
+
+- `web3AuthClientId` is renamed to `clientId`.
+- `network` is renamed to `web3AuthNetwork`.
+
+[Checkout Web3AuthOptions for available parameters](/docs/sdk/core-kit/sfa-ios/initialize#parameters).
+
+```swift
+// remove-start
+let singleFactorAuthArgs = SFAParams(
+    web3AuthClientId: "YOUR_WEB3AUTH_CLIENT_ID",
+    network: .sapphire(.SAPPHIRE_MAINNET)
+)
+// remove-end
+
+// add-start
+let web3AuthOptions = Web3AuthOptions(
+    clientId: "YOUR_WEB3AUTH_CLIENT_ID",
+    web3AuthNetwork: .SAPPHIRE_MAINNET
+)
+// add-end
+
+let singleFactoreAuth = SingleFactorAuth(
+    // remove-next-line
+    params: SFAParams
+    // add-next-line
+    params: web3AuthOptions
+)
+```
+
+### SFAKey is replaced with SessionData
+
+In v9, we removed the `SFAKey` and added the `SessionData` object to return the relveant session
+information like private key, address, user information, and signatures.
+
+```swift
+// remove-next-line
+let sfaKey: SFAKey = try await singleFactoreAuth.connect(loginParams: loginParams)
+// add-next-line
+let sessionData: SessionData = try await singleFactoreAuth.connect(loginParams: loginParams)
+```
+
+### getTorusKey method is now private
+
+The `getTorusKey` method is now private and can no longer be accessible. You can use the `connect`
+method to login user.
+
+```swift
+let loginParams = LoginParams(
+    verifier: "YOUR_VERIFIER_NAME",
+    verifierId: "VERIFIER_ID",
+    idToken: "ID_TOKEN"
+)
+
+// focus-start
+// remove-next-line
+let torusKey: TorusSFAKey = try await singleFactoreAuth.getTorusKey(loginParams: loginParams)
+// add-next-line
+let sessionData: SessionData = try await singleFactoreAuth.connect(loginParams: loginParams)
+// focus-end
+```
+
+### initialize method changes
+
+Starting v9, the `initialize` method will not return any value. To check whether the user already
+has an existing session, please use the `getSessionData` method. The `getSessionData` method will
+return `nil` if the user does not have an existing session.
+
+```swift
+// remove-next-line
+let sfaKey: SFAKey = try await singleFactoreAuth.initialize()
+// add-next-line
+try await singleFactoreAuth.initialize()
+
+// add-start
+let sessionData = singleFactoreAuth.getSessionData()
+if sessionData == nil {
+    // User does not have an existing session
+}
+// add-end
+```
+
+## Additional Features
+
+Apart from the breaking changes, we have added couple of new functions in v9 to improve the
+developer experience.
+
+### logout Method
+
+The `logout` method is added to the SDK to log out the user and clear the session data. Please note,
+that this method only logout the user and invalides the Web3Auth session, and not the OAuth provider
+session.
+
+```swift
+try await singleFactoreAuth.logout()
+```
+
+### getSessionData Method
+
+The `getSessionData` method is added to the SDK to get the session data. You can use this method to
+retrive the session data for an existing session. The method will return `nil` if the user does not
+have an existing session.
+
+#### Usage
+
+```swift
+let sessionData = singleFactoreAuth.getSessionData()
+
+if sessionData == nil {
+    // User does not have an existing session
+}
+```
+
+#### SessionData
+
+The `SessionData` has the following four functions to retrive the relevant session information.
+
+| Function Name      | Description                                                               |
+| ------------------ | ------------------------------------------------------------------------- |
+| `getPrivateKey`    | Retrieves the user's private key.                                         |
+| `getPublicAddress` | Retrieves the user's public address.                                      |
+| `getUserInfo`      | Retrieves the user's information like email, name, verifier id, and more. |
+| `getSignatures`    | Retrieves the node's signatures that are returned for request.            |
+
+### connected Method
+
+The `connected` method can be used to check whether the user is logged in Web3Auth or not. Please
+note, you should call this method after the `initialize` method if you want to check the user's
+connection status for an existing session.
+
+```swift
+let isConnected = singleFactoreAuth.connected()
+```

docs/sdk/core-kit/sfa-ios/initialize.mdx

@@ -6,20 +6,22 @@ description: "Web3Auth SFA Swift SDK - Initialization | Documentation - Web3Auth
 
 import Initialization from "@site/src/common/sdk/core-kit/sfa/ios/_sfa-ios-initialization.mdx";
 
-After Installation, the next step to use Web3Auth is to Initialize the SDK. Please note that these
-are the most critical steps where you need to pass on different parameters according to the
-preference of your project.
+After Installation, the next step to use Web3Auth is to create an instance, and initialize the SDK.
+Please note that these are the most critical steps where you need to pass on different parameters
+according to the preference of your project.
 
 ## Parameters
 
-The `SingleFactoreAuth` constructor takes an object called `SingleFactorAuthArgs` as input. The
+The `SingleFactoreAuth` constructor takes an object called `Web3AuthOptions` as input. The
 constructor parameters are listed below
 
-| Parameter          | Description                                                                                                                                                                                                      |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `web3AuthClientId` | Your Web3Auth Client Id from [Web3Auth Dashboard](https://dashboard.web3auth.io/).                                                                                                                               |
-| `network`          | The Web3auth network to be used by the SDK. Supported values are `.sapphire(.SAPPHIRE_MAINNET)`, `.sapphire(.SAPPHIRE_DEVNET)`, `.legacy(.MAINNET)`, `.legacy(.TESTNET)`, `.legacy(.CYAN)`, and `.legacy(.AQUA)` |
-| `sessionTime`      | Specifies the session duration in seconds. By default, the value is set to 86400 seconds (1 day), with a maximum session duration of up to 7 days.                                                               |
+| Parameter           | Description                                                                                                                                            |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `clientId`          | Your Web3Auth Client Id from [Web3Auth Dashboard](https://dashboard.web3auth.io/).                                                                     |
+| `web3AuthNetwork`   | The Web3auth network to be used by the SDK. Supported values are `.SAPPHIRE_MAINNET`, `.SAPPHIRE_DEVNET`, `.MAINNET`, `.TESTNET`, `.CYAN`, and `.AQUA` |
+| `sessionTime`       | Specifies the session duration in seconds. By default, the value is set to 86400 seconds (1 day), with a maximum session duration of up to 7 days.     |
+| `serverTimeOffset`  | Specifies the server time offset in seconds. This parameter is used to adjust the server time to the local time. The default value is 0 seconds.       |
+| `storageServerUrl?` | Specifies the storage server URL. The default value is `https://session.web3auth.io`.                                                                  |
 
 ## Initialize SingleFactorAuth
 

docs/sdk/core-kit/sfa-ios/usage.mdx

@@ -22,13 +22,15 @@ you'll see an Error message.
 The SingleFactorAuth instance natively provides the following methods:
 
 - [connect](#login-user) - Use to login user and retrive private key pair.
-- [initialize](#session-management) - This method helps to achieve session management. It
-  authenticates user if the session is present, avoiding re-logging.
+- [logout](#logout-user) - Use to logout existing user.
+- [connected](#check-users-logged-in-status) - Use to check whether the user is logged in or not.
+- [getSessionData](#get-session-data) - This method helps to get the session data for valid session.
 
 ## Login User
 
-To obtain a user's private key using the Web3Auth SFA Flutter SDK, you can call the `connect`
-method. The method accepts `LoginParams`, and returns `SFAKey`.
+To obtain a user's private key using the Web3Auth SFA iOS SDK, you can call the `connect` method.
+The method accepts `LoginParams`, and returns `SessionData`.
+[Please checkout the SessionData response for more details](#response).
 
 ### Parameters
 
@@ -48,6 +50,7 @@ method. The method accepts `LoginParams`, and returns `SFAKey`.
 | `verifierId`            | The verifierId used for the verification. It takes `String` as a value.                                  |
 | `idToken`               | The idToken of the user obtained from login provider. It takes `String` as a value.                      |
 | `subVerifierInfoArray?` | Sub verifier info. Usually used during aggregate verifier. It takes `[TorusSubVerifierInfo]` as a value. |
+| `serverTimeOffset?`     | Specifies the server time offset in seconds.                                                             |
 
 </TabItem>
 
@@ -59,19 +62,16 @@ public class LoginParams {
     public let verifierId: String
     public let idToken: String
     public let subVerifierInfoArray: [TorusSubVerifierInfo]?
+    public let serverTimeOffset: Int?
+    public let fallbackUserInfo: UserInfo?
 
-    public init(verifier: String, verifierId: String, idToken: String) {
-        self.verifier = verifier
-        self.verifierId = verifierId
-        self.idToken = idToken
-        subVerifierInfoArray = nil
-    }
-
-    public init(verifier: String, verifierId: String, idToken: String, subVerifierInfoArray: [TorusSubVerifierInfo]) {
+    public init(verifier: String, verifierId: String, idToken: String, subVerifierInfoArray: [TorusSubVerifierInfo]? = nil, serverTimeOffset: Int? = nil, fallbackUserInfo: UserInfo? = nil) {
         self.verifier = verifier
         self.verifierId = verifierId
         self.idToken = idToken
         self.subVerifierInfoArray = subVerifierInfoArray
+        self.serverTimeOffset = serverTimeOffset
+        self.fallbackUserInfo = fallbackUserInfo
     }
 }
 
@@ -94,18 +94,64 @@ public struct TorusSubVerifierInfo {
 ```swift
 let loginParams = LoginParams(verifier: "YOUR_VERIFIER_NAME", verifierId: "YOUR_VERIFIER_ID", idToken: "YOUR_ID_TOKEN")
 do {
-  let sfaKey = try await singleFactoreAuth.connect(loginParams: loginParams)
+  let sfaKey = try await singleFactorAuth.connect(loginParams: loginParams)
+} catch {
+  // Handle error
+}
+```
+
+## Logout User
+
+To logout the current user, you can use the `logout` method. Please note, the method will not logout
+the user from the authentication provider, it'll only logout and invalidate the Web3Auth session.
+
+### Usage
+
+```swift
+do {
+  try await singleFactorAuth.logout()
 } catch {
   // Handle error
 }
 ```
 
-## Session Management
+## Check User's Logged In Status
+
+You can use the `connected` method to check whether the user is logged in Web3Auth or not. Please
+note, you should call this method after the `initialize` method if you want to check the user's
+connection status for an existing session.
+
+### Usage
+
+```swift
+let isConnected = singleFactorAuth.connected()
+```
+
+## Get Session Data
 
-We have included Session Management in this SDK, so calling the initialize function to get the
-SFAKey value without re-logging in the user if a user has an active session will return the SFAKey,
-otherwise, it will throw an error.
+We have included Session Management in this SDK, so calling the `getSessionData` will retrive the
+user's `SessionData` without re-logging in the user if a user has an active session. Otherwise, it
+will return `nil`.
 
 ### Usage
 
-<SessionManagement />
+```swift
+let sessionData = singleFactorAuth.getSessionData()
+
+if(sessionData != nil) {
+  // User is logged in
+} else {
+  // User is not logged in
+}
+```
+
+### Response
+
+The `SessionData` has the following four functions to retrive the relevant session information.
+
+| Function Name      | Description                                                               |
+| ------------------ | ------------------------------------------------------------------------- |
+| `getPrivateKey`    | Retrieves the user's private key.                                         |
+| `getPublicAddress` | Retrieves the user's public address.                                      |
+| `getUserInfo`      | Retrieves the user's information like email, name, verifier id, and more. |
+| `getSignatures`    | Retrieves the node's signatures that are returned for request.            |

sidebars.ts

@@ -1611,7 +1611,11 @@ const sidebars: SidebarsConfig = {
     {
       type: "category",
       label: "Migration Guides",
-      items: ["migration-guides/sfa-ios-v7-to-v8", "migration-guides/sfa-ios-v2-to-v4"],
+      items: [
+        "migration-guides/sfa-ios-v8-to-v9",
+        "migration-guides/sfa-ios-v7-to-v8",
+        "migration-guides/sfa-ios-v2-to-v4",
+      ],
     },
     ...sdkQuickLinks,
   ],

src/common/sdk/core-kit/sfa/ios/_sfa-ios-cocoapods.mdx

@@ -3,7 +3,7 @@ To install the Web3Auth SingleFactorAuth SDK using Cocoapods, follow the below s
 1. Open the Podfile, and add the SingleFactorAuth pod:
 
 ```sh
-pod 'SingleFactorAuth', '~> 8.0.0'
+pod 'SingleFactorAuth', '~> 9.0.2'
 ```
 
 2. Once added, use `pod install` command to download the SingleFactorAuth dependency.

src/common/sdk/core-kit/sfa/ios/_sfa-ios-initialization.mdx

@@ -1,13 +1,21 @@
+The `initialize` method is responsible for authorizing the existing sessions, and initializing the
+SDK. If the existing session is not valid, it'll throw an error.
+
 ```swift
 import SingleFactorAuth
 
-let sfaParams = SFAParams(
-  web3AuthClientId: "YOUR_WEB3AUTH_CLIENT_ID",
-  network: .sapphire(.SAPPHIRE_MAINNET)
+let options = Web3AuthOptions(
+  clientId: "YOUR_WEB3AUTH_CLIENT_ID",
+  web3AuthNetwork: .SAPPHIRE_MAINNET,
+  // Sets a session for 2 days, takes the input
+  // in seconds.
+  sessionTime: 172800
 )
 
 do {
-  let singleFactoreAuth = try SingleFactorAuth(params: sfaParams)
+  let singleFactoreAuth = try SingleFactorAuth(params: options)
+
+  try await singleFactoreAuth.initialize()
 } catch {
   // Handle error
 }

src/common/sdk/core-kit/sfa/ios/_sfa-ios-spm.mdx

@@ -6,7 +6,7 @@
    https://github.com/Web3Auth/single-factor-auth-swift
    ```
 
-   From the `Dependency Rule` dropdown, select `Exact Version` and enter `8.0.0` as the version.
+   From the `Dependency Rule` dropdown, select `Exact Version` and enter `9.0.2` as the version.
 
 1. When finished, Xcode will automatically begin resolving and downloading your dependencies in the
    background.

src/common/versions.ts

@@ -8,7 +8,7 @@ export const pnpUnrealVersion = `4.1.x`;
 
 export const sfaWebVersion = `8.0.x`;
 export const sfaAndroidVersion = `1.2.0`;
-export const sfaIOSVersion = `8.0.0`;
+export const sfaIOSVersion = `9.0.2`;
 export const sfaRNVersion = `2.0.x`;
 export const sfaFlutterVersion = `5.2.0`;
 export const sfaNodeJSVersion = `7.4.x`;