npm package: @liftric/cognito-idp
Description: Lightweight AWS Cognito Identity Provider client.
Latest version: 4.0.0

![CI](https://github.com/Liftric/cognito-idp/workflows/CI/badge.svg) 
![maven-central](https://img.shields.io/maven-central/v/com.liftric/cognito-idp?label=Maven%20Central) 
![OSS Sonatype (Releases)](https://img.shields.io/nexus/r/com.liftric/cognito-idp?label=Sonatype%20OSSRH%20%28Releases%29&server=https%3A%2F%2Fs01.oss.sonatype.org)
![npm (scoped)](https://img.shields.io/npm/v/@liftric/cognito-idp)
![platforms](https://img.shields.io/badge/platforms-android%20%7C%20ios%20%7C%20jvm%20%7C%20js-blue)
# Cognito-idp

Lightweight AWS Cognito Identity Provider client for Kotlin Multiplatform and Typescript projects.

> Not all requests, errors, and auth flows are implemented.  
> Feel free to [contribute](Contributing.md) if there is something missing for you.

> Version 2 introduced breaking changes, please refer to the [migration](Migrating.md) document for help.

## Import

### Kotlin

#### Gradle 

```kotlin
sourceSets {
    val commonMain by getting {
        dependencies {
            implementation("com.liftric:cognito-idp:<version>")
        }
    }
}
```

### Typescript

#### Yarn
```bash
yarn add @liftric/cognito-idp@<version>
```
#### npm
```sh
npm i @liftric/cognito-idp@<version>
```

## How-to

### Init

#### Kotlin

```kotlin
val provider = IdentityProviderClient("<region>", "<clientId>") 
```

#### Typescript

```typescript
import {IdentityProviderClientJS} from '@liftric/cognito-idp';

const provider = new IdentityProviderClientJS('<region>', '<clientId>');
```

### Usage

#### Kotlin

All methods are suspending and return a `Result<T>`, which wraps the desired object `T` on success or a `Throwable` on failure.

```kotlin
provider.signUp("user", "password").fold(
    onSuccess = {
        // Do something
    },
    onFailure = {
        // Handle exceptions
    }
)
```

#### Typescript

All methods return a [Promise](https://developer.mozilla.org/de/docs/Web/JavaScript/Reference/Global_Objects/Promise)<T> object.

### Errors

Request related exceptions are defined as a sealed class of type `IdentityProviderException`. They contain the http `status` code and the `message`. Common AWS exceptions are implemented as subclasses. In case that we don't have implemented the exception type it will default to `IdentityProviderException.Unknown`, which will contain the AWS exception `type`.

Network related exceptions (e.g. no internet) are of type `IOException`.

### Requests 

#### Sign Up

Signs up the user.

Attributes are optional.

```kotlin
val attribute = UserAttribute("email", "name@url.tld")
signUp("<username>", "<password>", listOf(attribute)): Result<SignUpResponse>
```

#### Confirm Sign Up

Confirms the sign up (also the delivery medium).

```kotlin
confirmSignUp("<username>", "<confirmationCode>"): Result<Unit>
```

#### Resend Confirmation Code

Resends the confirmation code.

```kotlin
resendConfirmationCode("<username>"): Result<CodeDeliveryDetails>
```

#### Sign In

Signs in the users.

```kotlin
signIn("<username>", "<password>"): Result<SignInResponse>
```

#### Respond To Auth Challenge

Responds to the auth challenge of the sign in response.

```kotlin
val challengeResponses = mapOf<String, String>()
respondToAuthChallenge("<challengeName>", challengeResponses, "<session>"): Result<SignInResponse>
```

#### Refresh access token

Refreshes access token based on refresh token that's retrieved from an earlier sign in.

```kotlin
val signInResponse: SignInResponse = ... // from earlier login or refresh
val refreshToken = signInResponse.AuthenticationResult.RefreshToken
refresh(refreshToken): Result<SignInResponse>
```

#### Get Claims

You can retrieve the claims of both the IdTokens' and AccessTokens' payload by converting them to either a `CognitoIdToken` or `CognitoAccessToken`

```kotlin
val idToken = CognitoIdToken(idTokenString)
val phoneNumber = idToken.claims.phoneNumber
val sub = idToken.claims.sub
```

Custom attributes of the IdToken get mapped into `customAttributes`.

You have to drop the `custom:` prefix.

```kotlin
val twitter = idToken.claims.customAttributes["twitter"]
```

#### Get User

Returns the users attributes and metadata on success.

More info about this in the [official documentation](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUser.html).

```kotlin
getUser("<accessToken>"): Result<GetUserResponse>
```

#### Update User Attributes

Updates the users attributes (e.g. email, phone number, ...).

```kotlin
val attributes: List<UserAttribute> = ...
updateUserAttributes("<accessToken>", attributes): Result<UpdateUserAttributesResponse>
```

#### Change Password

Updates the users password 

```kotlin
changePassword("<accessToken>", "<currentPassword>", "<newPassword>"): Result<Unit>
```

#### Forgot Password

Invokes password forgot and sends a confirmation code the the users' delivery medium.

More info about the ForgotPasswordResponse in the [official documentation](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CodeDeliveryDetailsType.html).

```kotlin
forgotPassword("<username>"): Result<ForgotPasswordResponse>
```

#### Confirm Forgot Password

Confirms forgot password.

```kotlin
confirmForgotPassword("<confirmationCode>", "<username>", "<newPassword>"): Result<Unit>
```

#### Get user Attribute Verification Code

Gets the user attribute verification code for the specified attribute name

```kotlin
getUserAttributeVerificationCode("<accessToken>", "<attributeName>", "<clientMetadata>"): Result<GetAttributeVerificationCodeResponse>
```

#### Verify User Attribute

Verifies the specified user attribute.

```kotlin
verifyUserAttribute("<accessToken>", "<attributeName>", "<confirmationCode>"): Result<Unit>
```

#### Sign Out

Signs out the user globally.

```kotlin
signOut("<accessToken>"): Result<SignOutResponse>
```

#### Revoke Token

Revokes all access tokens generated by the refresh token.

```kotlin
revokeToken("<refreshToken>"): Result<Unit>
```


#### Associate Software Token

Associate software token. Either with access token or session (not both).

```kotlin
associateSoftwareToken("<accessToken>", "<session"): Result<AssociateSoftwareTokenResponse>
```

#### Verify Software Token

Verifies software token. Either with access token or session (not both).

```kotlin
verifySoftwareToken("<accessToken>", "<friendlyDeviceName>", "<session", "<userCode>"): Result<VerifySoftwareTokenResponse>
```

#### Set User MFA Preference

Set MFA preferences.

```kotlin
val smsMfaSettings = null
val softwareTokenMfaSettings = MfaSettings(true, true)
setUserMFAPreference("<accessToken>", smsMfaSettings, softwareTokenMfaSettings): Result<Unit>
```

#### Delete User

Deletes the user from the user pool.

```kotlin
deleteUser("<accessToken>"): Result<Unit>
```

## License

Cognito-idp is available under the MIT license. See the LICENSE file for more info.