diff --git a/docs/kotlin-multiplatform-sdk/helper.md b/docs/kotlin-multiplatform-sdk/helper.md index 7940d529..ba002a49 100644 --- a/docs/kotlin-multiplatform-sdk/helper.md +++ b/docs/kotlin-multiplatform-sdk/helper.md @@ -77,3 +77,178 @@ await sdk.helper.upload_platform_logo( + +## Assisted login + +Performs the standard login process in a single call. It performs the [login](account.md), generates a new +[key pair](crypto.md#generate-a-key-pair) when needed, and attempts to [register the ephemeral key](account.md#register-ephemeral-key). +If that registration is rejected because the user must verify their identity, it falls back to +[secondary authentication](account.md#register-ephemeral-key-with-secondary-authentication). + +:::info +* When used successfully, the **cloud auth token**, **cloud refresh token**, and the generated **key pair** +are added to the [context manager](context-manager.md) and automatically stored in +[secure storage](initialize.md#secure-storage). +* If the response has `requiresVerification = true`, the caller must invoke +[verify ephemeral key registration](account.md#verify-ephemeral-key-registration) with the code received by the +user (email, SMS, or telephone) to complete the process. +* If the response has `requiresRetry = true`, the secondary authentication endpoint was rate-limited and the +caller should retry later. +::: + +### Response + +| Field | Type | Description | +|----------------------|---------|--------------------------------------------------------------------------------------------| +| requiresVerification | Boolean | `true` when the caller must complete secondary authentication via `verifyEphemeralKeyRegistration` | +| requiresRetry | Boolean | `true` when the request was rate-limited and the caller should retry later | + + + + +```kotlin showLineNumbers +// Returns an AssistedLoginResponse +val response = sdk.helper().assistedLogin( + email = "EMAIL", + password = "PASSWORD" +) +``` + + + + +```java showLineNumbers +// Returns a CompletableFuture +var response = sdk.helper().assistedLoginAsync("EMAIL", "PASSWORD"); +``` + + + + +```swift showLineNumbers +// Returns an AssistedLoginResponse asynchronously +let response = await sdk.helper().assistedLogin( + email: "EMAIL", + password: "PASSWORD" +) +``` + + + + +```js showLineNumbers +// Returns a Promise +const response = await com.doordeck.multiplatform.sdk.api.helper().assistedLogin( + "EMAIL", + "PASSWORD" +); +``` + + + + +```csharp showLineNumbers +// Returns a Task +var response = await sdk.GetHelper().AssistedLogin( + email: "EMAIL", + password: "PASSWORD" +); +``` + + + + +```python showLineNumbers +# Returns a Future[SimpleNamespace] +response = await sdk.helper.assisted_login("EMAIL", "PASSWORD") +``` + + + + +## Assisted register ephemeral key + +Registers an ephemeral key in a single call. It first tries the standard +[register ephemeral key](account.md#register-ephemeral-key) endpoint and, if that is rejected because the +account is locked, automatically falls back to +[secondary authentication](account.md#register-ephemeral-key-with-secondary-authentication). + +:::info +* If your [context manager](context-manager.md) already has a public and private key, you can pass **null** +for those parameters, and the values will be retrieved from the [context manager](context-manager.md) instead. +* If the response has `requiresVerification = true`, the caller must invoke +[verify ephemeral key registration](account.md#verify-ephemeral-key-registration) with the code received by the +user (email, SMS, or telephone) to complete the process. +* If the response has `requiresRetry = true`, the secondary authentication endpoint was rate-limited and the +caller should retry later. +::: + +### Response + +| Field | Type | Description | +|----------------------|---------|--------------------------------------------------------------------------------------------| +| requiresVerification | Boolean | `true` when the caller must complete secondary authentication via `verifyEphemeralKeyRegistration` | +| requiresRetry | Boolean | `true` when the request was rate-limited and the caller should retry later | + + + + +```kotlin showLineNumbers +// Returns an AssistedRegisterEphemeralKeyResponse +val response = sdk.helper().assistedRegisterEphemeralKey(KEY_PAIR) +``` + + + + +```java showLineNumbers +// Returns a CompletableFuture +var response = sdk.helper().assistedRegisterEphemeralKeyAsync(KEY_PAIR); +``` + + + + +```swift showLineNumbers +// Returns an AssistedRegisterEphemeralKeyResponse asynchronously +let response = await sdk.helper().assistedRegisterEphemeralKey( + publicKey: PUBLIC_KEY, + privateKey: PRIVATE_KEY +) +``` + + + + +```js showLineNumbers +// Returns a Promise +const response = await com.doordeck.multiplatform.sdk.api.helper().assistedRegisterEphemeralKey( + PUBLIC_KEY, + PRIVATE_KEY +); +``` + + + + +```csharp showLineNumbers +// Returns a Task +var response = await sdk.GetHelper().AssistedRegisterEphemeralKey( + publicKey: PUBLIC_KEY, + privateKey: PRIVATE_KEY +); +``` + + + + +```python showLineNumbers +# Returns a Future[SimpleNamespace] +response = await sdk.helper.assisted_register_ephemeral_key( + "BASE64_PUBLIC_KEY", + "BASE64_PRIVATE_KEY" +) +``` + + +