Kmp sdk doc update

docs/kotlin-multiplatform-sdk/account.md

@@ -6,11 +6,12 @@
 This function is only available to users with Sentry Interactive issued auth tokens.
 :::
 
-:::info 
-* When used successfully, the **cloud auth token** and **cloud refresh token** 
-from the response are added to the [context manager](context-manager.md) and automatically stored in [secure storage](initialize.md#secure-storage).
-* This function can be used with the [refresh token](context-manager.md#set-cloud-refresh-token) value from the context. 
-To use the value from the context, you should pass **null** as the function parameter.
+:::info
+* When used successfully, the **cloud auth token** and **cloud refresh token**
+  from the response are added to the [context manager](context-manager.md) and automatically stored in [secure storage](initialize.md#secure-storage).
+* This function can be used with the [refresh token](context-manager.md#set-cloud-refresh-token) value from the context.
+  To use the value from the context, you should pass **null** as the function parameter.
+* The SDK also refreshes the tokens [automatically](context-manager.md#set-cloud-refresh-token).
 :::
 
 import Tabs from '@theme/Tabs';
@@ -70,7 +71,7 @@ response = await sdk.account.refresh_token("REFRESH_TOKEN")
 ## Logout
 
 :::warning
-When used, the [context manager](context-manager.md) restarts, and the values from the 
+When used, the [context manager](context-manager.md) restarts, and the values from the
 [secure storage](initialize.md#secure-storage) are automatically deleted.
 :::
 
@@ -130,11 +131,11 @@ await sdk.account.logout()
 To register a new ephemeral key, you will need to [generate a new key pair](crypto.md#generate-a-key-pair).
 
 :::info
-* When used successfully, both the supplied **private** and **public keys** are added to the 
-[context manager](context-manager.md) and automatically stored in [secure storage](initialize.md#secure-storage), 
-along with the **user ID** and **user certificate chain** from the response.
-* If your [context manager](context-manager.md) already has public and private keys, you can pass **null** 
-for those parameters, and those values will be retrieved from the [context manager](context-manager.md) instead.
+* When used successfully, both the supplied **private** and **public keys** are added to the
+  [context manager](context-manager.md) and automatically stored in [secure storage](initialize.md#secure-storage),
+  along with the **user ID** and **user certificate chain** from the response.
+* If your [context manager](context-manager.md) already has public and private keys, you can pass **null**
+  for those parameters, and those values will be retrieved from the [context manager](context-manager.md) instead.
 :::
 
 <Tabs groupId="programming-language">
@@ -202,12 +203,12 @@ response = await sdk.account.register_ephemeral_key(
 
 ## Register ephemeral key with secondary authentication
 
-To register a new ephemeral key with secondary authentication, 
-you will need to [generate a new key pair](crypto.md#generate-a-key-pair). 
+To register a new ephemeral key with secondary authentication,
+you will need to [generate a new key pair](crypto.md#generate-a-key-pair).
 After the registration, you will need to [verify the ephemeral key registration](#verify-ephemeral-key-registration).
 
-:::info 
-If your [context manager](context-manager.md) already has public key, you can pass **null** for that parameter, 
+:::info
+If your [context manager](context-manager.md) already has public key, you can pass **null** for that parameter,
 and the value will be retrieved from the [context manager](context-manager.md) instead.
 :::
 
@@ -268,11 +269,11 @@ response = await sdk.account.register_ephemeral_key_with_secondary_authenticatio
 ## Verify ephemeral key registration
 
 :::info
-* When used successfully, both the supplied **private** and **public keys** are added to the [context manager](context-manager.md) 
-and automatically stored in [secure storage](initialize.md#secure-storage), 
-along with the **user ID** and **user certificate chain** from the response.
-* If your [context manager](context-manager.md) already has public and private keys, you can pass **null** 
-for those parameters, and those values will be retrieved from the [context manager](context-manager.md) instead.
+* When used successfully, both the supplied **private** and **public keys** are added to the [context manager](context-manager.md)
+  and automatically stored in [secure storage](initialize.md#secure-storage),
+  along with the **user ID** and **user certificate chain** from the response.
+* If your [context manager](context-manager.md) already has public and private keys, you can pass **null**
+  for those parameters, and those values will be retrieved from the [context manager](context-manager.md) instead.
 :::
 
 <Tabs groupId="programming-language">
@@ -586,8 +587,9 @@ This operation is executed instantly and is irreversible.
 :::
 
 :::info
-When used, the [context manager](context-manager.md) restarts, and the values 
-from the [secure storage](initialize.md#secure-storage) are automatically deleted.
+When used successfully, the [context manager](context-manager.md) restarts, and the values
+from the [secure storage](initialize.md#secure-storage) are automatically deleted. If the request fails, the
+context is kept.
 :::
 
 <Tabs groupId="programming-language">

docs/kotlin-multiplatform-sdk/context-manager.md

@@ -1,9 +1,9 @@
 # Context manager
 
-The **Context Manager** simplifies the usage of complex SDK functions by reducing the number of parameters 
+The **Context Manager** simplifies the usage of complex SDK functions by reducing the number of parameters
 required when setting the operation context, authentication tokens, and other session data.
 
-:::info 
+:::info
 All the values that are provided to the context manager are automatically stored in [secure storage](initialize.md#secure-storage).
 :::
 
@@ -115,7 +115,9 @@ apiEnvironment = sdk.contextManager.get_api_environment()
 ## Set cloud auth token
 
 If the SDK was initialized without an authentication token, you can provide or update the token using this function,
-also it is set automatically by [login](accountless.md#login), [register](accountless.md#register-a-new-user), and [refresh-token](account.md#request-a-new-refresh-token).
+also it is set automatically by [login](accountless.md#login), [register](accountless.md#register-a-new-user),
+[refresh-token](account.md#request-a-new-refresh-token) and the [automatic refresh](#set-cloud-refresh-token).
+Passing **null** removes the stored token.
 
 <Tabs groupId="programming-language">
 <TabItem value="kotlin" label="Kotlin">
@@ -211,11 +213,14 @@ token = sdk.contextManager.get_cloud_auth_token()
 
 ## Is cloud auth token invalid or expired
 
-Checks if the current cloud auth token from the context is invalid, expired
-(we consider it expired if it will expire within the next 24 hours) or invalidated.
-When **checkServerInvalidation** is set to **true**, it also checks if the auth token has been invalidated on the backend.
-This requires a network request. When **checkServerInvalidation** is **false**, this server check is skipped,
-meaning the auth token might be accepted even if it has been invalidated on the server.
+Checks whether the cloud auth token from the context can still be used:
+
+* A token that is missing, invalid or expires within the next 24 hours is first refreshed with the stored
+  [refresh token](#set-cloud-refresh-token). This is a network request, performed regardless of **checkServerInvalidation**.
+* It returns **true** only when the token could not be refreshed and is missing, invalid or past its expiration.
+  A token that could not be refreshed but has not expired yet is still valid, since the backend accepts it until then.
+* When **checkServerInvalidation** is **true**, a token that passes the checks above is also verified with the backend
+  (an additional network request). When **false**, the token might be accepted even if it has been invalidated on the server.
 
 <Tabs groupId="programming-language">
 <TabItem value="kotlin" label="Kotlin">
@@ -270,8 +275,14 @@ result = await sdk.contextManager.is_cloud_auth_token_invalid_or_expired(True)
 
 ## Set cloud refresh token
 
-It is set automatically by [login](accountless.md#login), [register](accountless.md#register-a-new-user), 
-and [refresh-tokens](account.md#request-a-new-refresh-token).
+It is set automatically by [login](accountless.md#login), [register](accountless.md#register-a-new-user),
+and [refresh-tokens](account.md#request-a-new-refresh-token). Passing **null** removes the stored token.
+
+:::info
+While a refresh token is stored, the SDK refreshes the cloud auth token automatically: before a request, when the
+auth token is missing, invalid or expires within the next 24 hours, and once more after an unauthorized response.
+A refresh token rejected by the backend is removed from the context.
+:::
 
 <Tabs groupId="programming-language">
 <TabItem value="kotlin" label="Kotlin">
@@ -570,7 +581,7 @@ token = sdk.contextManager.get_fusion_auth_token()
 ## Set user ID
 
 Sets the user identifier used by the secure [lock operations](lock-operations.md). It is usually set for you by
-[set operation context](#set-operation-context), [register ephemeral key](account.md#register-ephemeral-key) 
+[set operation context](#set-operation-context), [register ephemeral key](account.md#register-ephemeral-key)
 and [verify ephemeral key](account.md#verify-ephemeral-key-registration).
 
 <Tabs groupId="programming-language">
@@ -933,7 +944,7 @@ Sets the key pair used to sign the secure [lock operations](lock-operations.md).
 and [verify ephemeral key](account.md#verify-ephemeral-key-registration).
 
 :::info
-Setting a new key pair does **not** mark it as verified. Use [set key pair verified](#set-key-pair-verified), 
+Setting a new key pair does **not** mark it as verified. Use [set key pair verified](#set-key-pair-verified),
 or register it through [register ephemeral key](account.md#register-ephemeral-key) plus and [verify ephemeral key](account.md#verify-ephemeral-key-registration).
 :::
 
@@ -1044,7 +1055,7 @@ Marks a public key as verified, meaning it has successfully completed
 [two-factor verification](account.md#verify-ephemeral-key-registration). Pass **null** to clear the verification.
 
 :::info
-[Is key pair verified](#is-key-pair-verified) compares the value stored here against the current public key, 
+[Is key pair verified](#is-key-pair-verified) compares the value stored here against the current public key,
 so setting a key pair that does not match clears the verified state in practice.
 :::
 
@@ -1271,10 +1282,9 @@ sdk.contextManager.set_operation_context(
 
 Checks the state of the context by verifying that the [auth token is valid](#is-cloud-auth-token-invalid-or-expired),
 the [key pair is valid](#is-key-pair-valid) and [verified](#is-key-pair-verified),
-and the [certificate chain is valid](#is-certificate-chain-invalid-or-expired).
-When **checkServerInvalidation** is set to **true**, it also checks if the auth token has been invalidated on the backend.
-This requires a network request. When **checkServerInvalidation** is **false**, this server check is skipped,
-meaning the auth token might be accepted even if it has been invalidated.
+and the [certificate chain is valid](#is-certificate-chain-invalid-or-expired). The first check to fail determines
+the returned state. **checkServerInvalidation** behaves as described in
+[is cloud auth token invalid or expired](#is-cloud-auth-token-invalid-or-expired).
 
 <Tabs groupId="programming-language">
 <TabItem value="kotlin" label="Kotlin">

docs/kotlin-multiplatform-sdk/crypto.md

@@ -11,7 +11,7 @@ Each platform uses its own crypto provider and its own native key encoding:
 |          JVM          |  Java Security API  |
 |        Android        |    Bouncy Castle    |
 | iOS / macOS / watchOS |   Apple CryptoKit   |
-|  JS / Broswer / Node  |      Libsodium      |
+|  JS / Browser / Node  |      Libsodium      |
 |      C# / Python      |      Libsodium      |
 
 ## Generate a key pair

docs/kotlin-multiplatform-sdk/initialize.md

@@ -16,7 +16,8 @@ The minimum viable `SdkConfig` is `SdkConfig.Builder().build()`, although the fo
 |           Debug Logging           |      `setDebugLogging`      |         false          |
 
 :::info
-If you initialize the SDK without a cloud auth token, you will need to either provide one manually through the [context manager](context-manager.md#set-cloud-auth-token) or call the [login](accountless.md#login) function to access most SDK functionalities.
+* If you initialize the SDK without a cloud auth token, you will need to either provide one manually through the [context manager](context-manager.md#set-cloud-auth-token) or call the [login](accountless.md#login) function to access most SDK functionalities.
+* The SDK logs at **info** level by default. Enabling debug logging also prints the **debug** messages.
 :::
 
 ## Secure storage
@@ -38,6 +39,11 @@ To override the default secure storage, you must implement the `SecureStorage` i
 
 ## Initialize
 
+Initialization sets up the HTTP clients and the crypto provider, and synchronizes the SDK clock with the server
+(waiting up to 10 seconds for the first synchronization). If it fails, the acquired resources are released and
+the exception is rethrown. Initializing an already initialized SDK throws an `SdkException`; [release](#release)
+it first.
+
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
@@ -51,10 +57,6 @@ val sdkConfig = SdkConfig.Builder()
 val sdk = KDoordeckFactory.initialize(sdkConfig)
 ```
 
-:::info
-You should also call `sdk.release()` at the end of your application's lifecycle to release the SDK resources.
-:::
-
 </TabItem>
 <TabItem value="java" label="Java">
 
@@ -65,10 +67,6 @@ var sdkConfig = SdkConfig.Builder()
 var sdk = KDoordeckFactory.INSTANCE.initializeAsync(sdkConfig);
 ```
 
-:::info
-You should also call `sdk.release();` at the end of your application's lifecycle to release the SDK resources.
-:::
-
 </TabItem>
 <TabItem value="swift" label="Swift">
 
@@ -79,10 +77,6 @@ let sdkConfig = SdkConfig.Builder()
 let sdk = await KDoordeckFactory().initialize(sdkConfig: sdkConfig)
 ```
 
-:::info
-You should also call `sdk.release()` at the end of your application's lifecycle to release the SDK resources.
-:::
-
 </TabItem>
 <TabItem value="js" label="JavaScript">
 
@@ -96,31 +90,70 @@ const sdk = await com.doordeck.multiplatform.sdk.KDoordeckFactory.initialize(
 );
 ```
 
-:::info
-You should also call `sdk.release()` at the end of your application's lifecycle to release the SDK resources.
-:::
-
 </TabItem>
 <TabItem value="csharp" label="C#">
 
 ```csharp showLineNumbers
 var sdk = new DoordeckSdk(cloudAuthToken: "AUTH_TOKEN");
 ```
 
-:::info
-You should also call `sdk.Release();` at the end of your application’s lifecycle to release the SDK resources.
-:::
-
 </TabItem>
 <TabItem value="python" label="Python">
 
 ```python showLineNumbers
 sdk = doordeck_headless_sdk.InitializeSdk(cloud_auth_token="AUTH_TOKEN")
 ```
 
-:::info
-You should also call `sdk.release()` at the end of your application's lifecycle to release the SDK resources.
-:::
+</TabItem>
+</Tabs>
+
+## Release
+
+Call it at the end of your application's lifecycle. It stops the background tasks and closes the HTTP clients,
+giving the in-flight requests up to 5 seconds to finish. The stored [context](context-manager.md) is kept, so
+releasing the SDK does not log the user out. Releasing an SDK that is not initialized does nothing.
+
+<Tabs groupId="programming-language">
+<TabItem value="kotlin" label="Kotlin">
+
+```kotlin showLineNumbers
+KDoordeckFactory.release()
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java showLineNumbers
+KDoordeckFactory.INSTANCE.releaseAsync();
+```
+
+</TabItem>
+<TabItem value="swift" label="Swift">
+
+```swift showLineNumbers
+await KDoordeckFactory().release()
+```
+
+</TabItem>
+<TabItem value="js" label="JavaScript">
+
+```javascript showLineNumbers
+await com.doordeck.multiplatform.sdk.KDoordeckFactory.release();
+```
+
+</TabItem>
+<TabItem value="csharp" label="C#">
+
+```csharp showLineNumbers
+sdk.Release();
+```
+
+</TabItem>
+<TabItem value="python" label="Python">
+
+```python showLineNumbers
+sdk.release()
+```
 
 </TabItem>
 </Tabs>

docs/kotlin-multiplatform-sdk/install.md

@@ -21,7 +21,7 @@ implementation("com.doordeck.headless.sdk:doordeck-sdk:[SDK_VERSION]")
 ```
 
 :::info[Requirements]
-* Supported Platforms: JVM, Android, jsNode, jsBrowser, iOS (x64, ARM x64, simulator ARM x64), macOS (ARM x64), watchOS (x64, ARM x64, device ARM x64, simulator ARM x64) and mingW (x64).
+* Supported Platforms: JVM, Android, jsNode, jsBrowser, iOS (ARM64, simulator ARM64), macOS (ARM64), watchOS (ARM64, device ARM64, simulator ARM64) and mingW (x64).
 * Java SDK 1.8 or higher.
 :::
 
@@ -64,12 +64,8 @@ implementation("com.doordeck.headless.sdk:doordeck-sdk-android:[SDK_VERSION]")
 </TabItem>
 <TabItem value="swift" label="Swift">
 
-The iOS, macOS and watchOS packages are available via [CocoaPods](https://cocoapods.org/pods/DoordeckSDK) and [Swift Package Manager (SPM)](https://github.com/doordeck/doordeck-headless-sdk-spm).
+The iOS, macOS and watchOS packages are available via [Swift Package Manager (SPM)](https://github.com/doordeck/doordeck-headless-sdk-spm).
 
-#### Cocoapods
-```pod 'DoordeckSDK', '~> [SDK_VERSION]'```
-
-#### Swift Package manager
 1. In Xcode, select **File > Add Package Dependencies...**.
 2. Enter the URL: [https://github.com/doordeck/doordeck-headless-sdk-spm](https://github.com/doordeck/doordeck-headless-sdk-spm).
 3. Choose **Up to next major version** from the dependency rule dropdown, and click **Add Package**.