# Suspension Service

If you only require specific functionality from the suspension service, you can import the `SuspensionService` module separately to the main SDK.

For example:

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

## Table of Contents

* [Config](#config)
	* [How to obtain a key](#how-to-obtain-a-key)
* [Methods](#methods)
	* [getSuspensions](#getSuspensions)
	* [getSuspensionById](#getSuspensionById)
	* [createSuspension](#createSuspension)
	* [endSuspension](#endSuspension)
	* [deleteSuspension](#deleteSuspension)
	* [getSummary](#getSummary)
* [Membership Response](#membership-response)
* [Membership Documentation](#membership-documentation)

## Config

* See common configuration options in the [README file](./README.doc)
* `suspensionApiKey`

```javascript
const config = new ProductionConfiguration({
	suspensionApiKey: 'secret',
	originSystemId: 'n-membership-sdk',
});
```

### How to obtain a key

Do one of the following:

1. Check in Doppler for your app to see if the API key you need already exists.
2. Contact #membership-support slack channel for a key for the service i.e. suspension-svc.

## Methods

### getSuspensions

```javascript
const suspensions = suspensionService.getSuspensions(subscriptionNumber);
```

| Parameters  | Required | Type   | Example | Description   |
| ----------- | -------- | -------| --------| ------------- |
| subscriptionNumber | yes | String | A-XXXXXXXXXXX | User's subscription number. |

**Response**: [Suspension model](../../src/models/suspension.ts)

### getSuspensionById

```javascript
const suspension = suspensionService.getSuspensionById(suspensionId);
```

| Parameters  | Required | Type   | Example | Description   |
| ----------- | -------- | -------| --------| ------------- |
| suspensionId | yes | String | xxxxxxxxx-xxxxx-xxxx-xxxxx-xxxxxxxxxxxxx | Specific suspension ID |

**Response**: [Suspension model](../../src/models/suspension.ts)

### createSuspension

```javascript
const suspension = suspensionService.createSuspension(subscriptionNumber, startDate, fromDate);
```

| Parameters  | Required | Type   | Example | Description   |
| ----------- | -------- | -------| --------| ------------- |
| subscriptionNumber | yes | String | A-XXXXXXXXXXX | User's subscription number. |
| startDate | yes | String | 2019-09-26 | The date the user wants to start their suspension. Format yyyy-MM-dd |
| endDate | yes | String | 2019-09-31 | The date the user wants to end their suspension. Format yyyy-MM-dd |

**Response**: [Suspension model](../../src/models/suspension.ts)

### endSuspension

```javascript
const endedSuspension = suspensionService.endSuspension(suspensionId);
```

You can only END a suspension that is currently in progress. The earliest endDateFrom can be is the LastDeliveryDate, as returned by [getLastDeliveryDateGenerated method](PRINT-INFO.md#getLastDeliveryDateGenerated). Although the `endDateFrom` parameter is not compulsory here or in the API (as of May 2020), leaving this field empty causes issues with the Delivery files, Membership has advised to always pass in the `endDateFrom` parameter.

Example, assuming delivery each day and no bank holidays: Initial suspension is from 1st to 20th. On the 10th user wants to end this suspension. LastDeliveryDate returns 11th. As such the 11st is the earliest the suspension can be ended - but could also be ended on the 15th.


| Parameters  | Required | Type   | Example | Description   |
| ----------- | -------- | -------| --------| ------------- |
| suspensionId | yes | String | xxxxxxxxx-xxxxx-xxxx-xxxxx-xxxxxxxxxxxxx | Specific suspension ID |
| endDateFrom | no | String | 2019-09-26 | Date to end the suspension. Format yyyy-MM-dd. |

**Response**: [Suspension model](../../src/models/suspension.ts)

**Note**: The [config](#Config) must contain the `originSystemId` and `originUser`. The request will not work without these values.

### deleteSuspension

```javascript
const deleteSuspension = suspensionService.deleteSuspension(suspensionId);
```

You can only DELETE a suspension that has not yet started. 

| Parameters  | Required | Type   | Example | Description   |
| ----------- | -------- | -------| --------| ------------- |
| suspensionId | yes | String | xxxxxxxxx-xxxxx-xxxx-xxxxx-xxxxxxxxxxxxx | Specific suspension ID |

**Response**: 204 status

**Note**: The [config](#Config) must contain the `originSystemId` and `originUser`. The request will not work without these values.

### getSummary

```javascript
const suspensionSummary = suspensionService.getSummary(subscriptionNumber);
```

| Parameters  | Required | Type   | Example | Description   |
| ----------- | -------- | -------| --------| ------------- |
| subscriptionNumber | yes | String | A-XXXXXXXXXXX | User's subscription number. |

**Response**:
```javascript
{
	subscriptionNumber: 'number',
	creditsTotal: 10,
	creditsUsed: 2,
	creditsRemaining: 8,
	periodStartDate: '2019-08-16',
	periodEndDate: '2020-08-15'
}
```

## Membership response

Suspensions:

```json
{
	"items": [
		{
			"suspensionId": "xxxxxxxxx-xxxxx-xxxx-xxxxx-xxxxxxxxxxxxx",
			"subscriptionNumber": "A-XXXXXXXXXXX",
			"startDate": "2019-08-16",
			"endDate": "2019-08-20",
			"credits": 4,
			"editions": 4,
			"status": "Logged",
			"originSystem": "https://cmdb.ft.com/systems/n-membership-sdk",
			"originUser": "customer",
			"createdDate": "2019-08-13T15:14:53",
			"updatedDate": "2019-08-13T15:14:53",
			"suspensionType": "standard",
			"updatedBy": null
		}
	]
}
```

Summary:

```json
{
	"subscriptionNumber": "A-XXXXXXXXXXX",
	"creditsTotal": 24,
	"creditsUsed": 0,
	"creditsRemaining": 24,
	"periodStartDate": "2019-10-08",
	"periodEndDate": "2020-10-07"
}
```

## Membership Documentation

| API Documentation | Confluence  | Description | Owner |
| -------------- | -------- | -------- | -------- |
| [Supension API](https://newspaper-suspensions-svc-lb-eu-west-1-prod.memb.ft.com/__api) |  [Suspension Documentation](https://confluence.ft.com/plugins/servlet/mobile?contentId=86310958#content/view/11239471) | Documentation for the suspension service | FT Core - Membership |