# User Service

## Request

If you only require User API functionality, you can import the module separately to the main SDK.

For example:

```javascript
const { User } = require('n-membership-sdk');
const userSDK = new User(config);
```

## Table of Contents

* [User Service](#user-service)
  * [Request](#request)
  * [Table of Contents](#table-of-contents)
  * [Config](#config)
    * [How to obtain a key](#how-to-obtain-a-key)
  * [Methods](#methods)
    * [doesUserExist](#doesuserexist)
    * [getUserResources](#getuserresources)
    * [createProfile](#createprofile)
    * [updateProfile](#updateprofile)
    * [changeEmail](#changeemail)
  * [Documentation](#documentation)

## Config

* See common configuration options in the [README file](./README.doc)
* `userProfileServiceApiKey` - Needed for [`doesUserExist`](#doesuserexist), [`getUserResources`](#getuserresources), [`createProfile`](#createprofile), [`updateExternalUserId`](#updateExternalUserId), [`changeEmail`](#changeemail) and [`updateProfile`](#updateprofile).
* `requestUserPurgeApiKey` - Needed for [`requestPurge`](#requestPurge).

```javascript
const config = new ProductionConfiguration({
    userProfileServiceApiKey: 'secret',
	userChangeEmailApiKey: 'secret',
	requestUserPurgeApiKey: 'secret',
});
```

### How to obtain a key

To obtain a key, do one of the following:

1. Check in Doppler for your app to see if a user (aka profile) service API key already exists.
2. Contact #membership-support slack channel for a user service key.

## Methods

### doesUserExist

- Check if a user exists for the given email address

```javascript
const userInfo = userSDK.doesUserExist(email);
```

| Parameters    | Required | Type   | Example | Description   |
| ------------- | -------- | -------| --------| ------------- |
| email         | Yes      | String | some@email.com | User's email address   |

**Response**:
Boolean true/false

### getUserResources

- Retrieve user resource given an email address. Returns a collection (size 0 or 1) of ‘user resources’ that matches the email address provided. Zero items (empty collection) indicates that no user was found for that email address. If a user with that email is found, the collection will contain exactly one item. More info at [docs-membership-platform-api-user-api-get-users-email](https://developer.ft.com/portal/docs-membership-platform-api-user-api-get-users-email).

```javascript
const userResources = userSDK.getUserResources(email);
```

| Parameters    | Required | Type   | Example | Description   |
| ------------- | -------- | -------| --------| ------------- |
| email         | Yes      | String | some@email.com | User's email address   |

**Membership Response**:
```javascript
{
    "items": [
        {
            "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "href": "/users/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        }
    ]
}
```

### createProfile

- Create a new FT user profile

```javascript
const userInfo = userSDK.createProfile(user);
```

| Parameters       | Required | Type   | Example | Description   |
| ---------------- | -------- | -------| --------| ------------- |
| user             | Yes      | Object | [User](../../src/models/user.ts)| User's details. Minimum requirements: email, password and country - ISO 3166-1 Alpha-3 country code. |
| sendRegistrationEmail | No  | boolean | `true`   | Triggers a registration email to the user if set to `true`. Optional, defaults to `false`. |

**Membership Response**:
```javascript
{
    "user": {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "email": "some@email.com",
        "title": null,
        "firstName": null,
        "lastName": null,
        "nonLogin": false,
        "primaryTelephone": null,
        "organisationName": null,
        "homeAddress": {
            "line1": null,
            "line2": null,
            "townCity": null,
            "state": null,
            "postcode": "90210",
            "country": "USA"
        },
        "marketing": null,
        "demographics": {
            "industry": null,
            "position": null,
            "responsibility": null
        },
        "jobTitle": null,
        "source": "legacy-api-user",
        "nonLogin": false,
        "href": "/users/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "country": "GBR",
        "postcode": "SE19HL"
    }
}
```

### updateProfile

- Update an existing FT user profile

```javascript
const userInfo = userSDK.updateProfile(user, authorisationToken);
```

| Parameters         | Required | Type   | Example | Description   |
| ------------------ | -------- | -------| --------| ------------- |
| user               | Yes      | Object | [User](../../src/models/user.ts)| User's details. Minimum requirements: email, password and country - ISO 3166-1 Alpha-3 country code. |
| authorisationToken | yes   | String | zx2bI... | Obtained from [authorisation.getToken](AUTHORISATION.md#getToken) |

**Membership Response**:
```javascript
{
    "user": {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "email": "some@email.com",
        "title": null,
        "firstName": null,
        "lastName": null,
        "primaryTelephone": null,
        "organisationName": null,
        "homeAddress": {
            "line1": null,
            "line2": null,
            "townCity": null,
            "state": null,
            "postcode": "SE19HL",
            "country": "GBR"
        },
        "marketing": {
            "ftByEmail": false,
            "ftByPost": false
        },
        "demographics": {
            "industry": null,
            "position": null,
            "responsibility": null
        },
        "jobTitle": null,
        "source": "legacy-api-user",
        "nonLogin": false,
        "href": "/users/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
}
```

### updateExternalUserId

- Change an existing FT user's externalUserId

```javascript
const hasUpdatedExternalUserId = await userSDK.updateExternalUserId(user, authorisationToken);
```

| Parameters         | Required | Type   | Example | Description   |
| ------------------ | -------- | -------| --------| ------------- |
| user               | Yes      | Object | [User](../../src/models/user.ts)| User's details. Minimum requirements: email, password and country - ISO 3166-1 Alpha-3 country code. |
| authorisationToken | yes   | String | zx2bI... | Obtained from [authorisation.getToken](AUTHORISATION.md#getToken) |

**Membership Response**:
The function returns true if it completed successfully, otherwise it will throw
```javascript
true | new Error()
```

### changeEmail

- Change an existing FT user's email address.

```javascript
const newEmailAddress = userSDK.changeEmail(userId, email, authorisationToken);
```

| Parameters         | Required | Type   | Example | Description   |
| ------------------ | -------- | -------| --------| ------------- |
| userId             | Yes      | String | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | The ID for the user whose email address we are changing. |
| email              | Yes      | String | "bruce.wayne@ftqa.org" | The user's new email address. |
| authorisationToken | yes   | String | zx2bI... | Obtained from [authorisation.getToken](AUTHORISATION.md#getToken) |

**Membership Response**:
```javascript
"bruce.wayne@ftqa.org"
```

### requestPurge

- Purge a user.

Note that **an api key is required to use this method**, request in #aim-support.

```javascript
const membershipResponse = userSDK.requestPurge(userId, deletionCategory);
```

| Parameters         | Required | Type   | Example | Description   |
| ------------------ | -------- | -------| --------| ------------- |
| userId             | Yes      | String | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` | The ID for the user we are purging. |
| deletionCategory   | Yes      | String | `"Test User"` | The reason for user purge. One of the following: `"Erasure Request"`, `"Retention Policy"`  or `"Test User"`.|


**Membership Response**:
```javascript
{
  "status": 201,
  "ok": true
}
```

## Documentation

| Documentation     | Description | Owner |
| -------------- | -------- | -------- |
| [User Profile API](https://user-profile-svc-lb-eu-west-1-prod.memb.ft.com/__api) | Documentation for the User Profile API | FT Core - Membership |