npm package: @financial-times/next-ft-developer-client
Description: Client for FT Next apps to communicate with the FT Developer API
Author: Financial Times
Latest version: 3.1.0
Deprecated: no longer maintained

# next-ft-developer-client [![Circle CI](https://circleci.com/gh/Financial-Times/next-ft-developer-client/tree/master.svg?style=svg)](https://circleci.com/gh/Financial-Times/next-ft-developer-client/tree/master)

This modules provides a client for calling the [FT Developer API](https://developer.ft.com)

## Requirements

* Node.js 4+
* An FT Developer API Key (request from membership-platform-api-key-request@ft.com, see https://developer.ft.com/docs/membership_platform_api/)
* If querying the user profile data, you will also need a Client ID (request from membership-platform-api-key-request@ft.com, https://developer.ft.com/docs/membership_platform_api/api_authz_svc/Client_Registration_Process)

## Install
`npm install @financial-times/next-ft-developer-client --save`

Set up the following environmental variables:

* FT_DEVELOPER_API_URL - https://api.ft.com/
* FT_DEVELOPER_API_KEY - your API key
* FT_DEVELOPER_CLIENT_NAME - your client ID

*FT Next products already have these available*

## Security

Calls to get user data *must* be made over HTTPS

### Authorisation tokens

For some API calls, the FT Developer API uses the `FT_Session_s` cookie to identify the user session. This is similar to the `FT_Session` cookie, but is a secure (https-only) cookie.

For FT Next apps, it is available via the `FT-Session-s-Token` header.

## Usage

```javascript
const nextFTDeveloperClient = require('@financial-times/next-ft-developer-client');
```

### User profile

User profile always requires the user ID and FT_Session_s token

```javascript

// get the full unadulterated user profile data
nextFTDeveloperClient.getUserProfile(FTSessionSToken, uuid).then(etc...);

// get a single item, like the user's email
const options = { fields: 'email' };
nextFTDeveloperClient.getUserProfile(FTSessionSToken, uuid, options).then(etc...);
// returns 'someone@somewhere.com'

// get multiple items, like the user's email and first name
const options = {
	fields: ['email', 'firstName']
};
nextFTDeveloperClient.getUserProfile(FTSessionSToken, uuid, options).then(etc...);
// returns { email: 'someone@somewhere.com', firstName: 'Someone' }

// send through scope
const options = {
	scope: 'profile_dem'
}
nextFTDeveloperClient.getUserProfile(FTSessionSToken, uuid, options).then(etc...);
// returns user data as per that scope
```

#### Mapped user profile items

* email
* firstName
* lastName
* primaryTelephone
* homeAddress
* address1
* address2
* townCity
* postcode
* state
* country
* marketing
* ftByEmail
* ftByPost
* demographics
* industry
* position
* responsibility
* href

If you enter a bad key name, logger will log a warning, and your returned object will only have valid keys

### User products

User products only require the user ID.

```javascript
// get the user's products
nextFTDeveloperClient.getUserProducts(uuid);
// returns an array of product codes, e.g ['P0', 'Tools']

```

## Contributing

* Clone this repo
* Make your changes on a branch
* Merge into master (with approval)
* The module will automatically publish to npm upon a new master tag (`v.X.X.X`)