npm package: @lightspeed/cts-client
Description: CTS Client API
Author: Lightspeed
Latest version: 1.0.0

# Lightspeed Card Tokenization Service Module

## About

This project is a module to handle generating credit card tokens in a way that limits exposure of the module
client to credit card information. This has the affect of limiting a client's scope with regard to PCI
compliance.

The module provides a facility for generating an iFrame which refers to an application hosted
on the Card Tokenization Service (CTS). It also provides a facility for on-demand generation of
the any card information entered into the fields provided by the CTS application.

## Basic Usage

Install the project's dependencies:

```bash
yarn install
```

Run the unit tests. This will produce coverage files in the `jest/coverage` directory. This is the command that
would typically be used on the CI server:

```bash
yarn test
```

Run the unit tests in a watch mode. This allows for quick iteration while developing tests:

```bash
yarn test:dev
```

Builds the assets (rolled-up) for development:

```bash
yarn build
```

To bump the version of the package and automatically update the CHANGELOG:

```bash
yarn bump
```

Prepares the package for publishing:

```bash
yarn prepublish
```

## CTS Client API

### `CTSClient.renderCardFields(options)`

The `CTSClient.renderCardFields` generates an iFrame linking to the CTS and returns a `CTSClient` instance. The generated instance may later be used to generate card tokens via the `generateToken` method.

The `options` parameter is an object which accepts the following attributes:

| attribute                        | type     | description                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`                          | `string` | The JWT obtained by the client to authenticate with the CTS (see above). If the JWT was generated with the `tst` field set to true then the card token will be generated using the gateway providers test environment otherwise the gateway providers production environment will be utilized.                                                                                                                                                                                     |
| `orderID`                        | `string` | A unique ID representing the order (or sale) for the transaction. It is the responsibility of the client application to ensure that this ID is unique.                                                                                                                                                                                                                                                                                                                             |
| `customerID`                     | `string` | An ID that uniquely identifies the customer associated with a transaction. It is the responsibility of the client application to ensure that this ID is unique.                                                                                                                                                                                                                                                                                                                    |
| `elementID`                      | `string` | A DOM `id` of an element with the client's application where the CTS iFrame is to be attached.                                                                                                                                                                                                                                                                                                                                                                                     |
| `gatewayConfigID`                | `string` | The ID of the gateway that will be used to generate the transaction token. The ID would come from the Payment Service.                                                                                                                                                                                                                                                                                                                                                             |
| `environment`                    | `string` | May be one of the following: `local`, `staging` or `production`. The value used will indicate under which environment the CTS iFrame will be generated. For example, if `local` is used the iFrame will link to the local environment.                                                                                                                                                                                                                                             |
| `...additionalGatewayAttributes` | `object` | If you need provide any additional attributes such as the cardholder information simply add those as single `key:value` pair or provide a complex structured object (max depth limit `5`). These attributes are optional and might not be supported for all gateway services. These are typically for fraud prevention. Any unsupported attribute will be ignored. Any name collision with the attributes stated before might result in unexpected behavior, you have been warned. |

Since there are asynchronous operations that need to occur to generate the iFrame, the `CTSClient` instance will be returned once the `Promise` returned by a call to the `CTSClient.renderCardFields` method resolves. If there was an error generating then the promise will reject with an appropriate error message:

| error                  | description                                                |
| ---------------------- | ---------------------------------------------------------- |
| 'AUTHENTICATION_ERROR' | The supplied `token` and/or `gatewayConfigID` was invalid. |
| 'INVALID_PARAMETERS'   | One or more required parameters was invalid.               |
| 'UNKNOWN'              | An unexpected error has occurred.                          |

Example:

```javascript
import CTSClient from '@lightspeed/cts-client';

let ctsClient = null;

CTSClient.renderCardFields({
  token: 'some-valid-token',
  orderID: 'uinque-order-id',
  customerID: 'totally-unique-customer-id',
  elementID: 'my-container', // assumes that an HTML element with the id #my-container exists
  gatewayConfigID: 'legit-gateway-config-id', // obtained from the payment service
  environment: 'local', // use the local environment for token generation
})
  .then((client) => {
    ctsClient = client; // store the client for later use
  })
  .catch((error) => {
    // do something useful with the error
  });
```

### `generateToken(reportGroup, clientTransactionID)`

The `generateToken` instance method is a method used to generate a token with fields rendered and maintained by the CTS. It requires two parameters:

| parameter             | description                                                                                                                                                     |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reportGroup`         | A client-specified ID used to categorize the merchant transactions. Most likely would be the same ID as used by the client to identify the Lightspeed customer. |
| `clientTransactionID` | A client-specified ID used to identify the transaction.                                                                                                         |

Th `generateToken` method resolves with a `Promise` when the operation is complete (whether it is is successful or not). The `Promise` response is an object which takes the following form:

| attribute              | type   | description                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`                | string | The generated card token. This token may be used to perform the transaction in lieu of card data. The client application back-end is responsible for providing proper support to allow forwarding the token to the Payment Service when performing a transaction. If token was not successfully generated then this attribute will not be provided in the response. |
| `error`                | string | The general error that has occurred generating the token. Only provided if there was an error.                                                                                                                                                                                                                                                                      |
| `additionalParameters` | object | The original response returned by the third-party token generation API. This may be used by the client application to show gateway-specific status messages, transaction information, etc.                                                                                                                                                                          |

Example:

```javascript
ctsClient.generateToken('merchantId', 'some-unique-transaction-id').then((response) => {
  const { token, error } = response;

  if (token) {
    console.log('Congratulateions!  Your token is:', token);
  } else if (error) {
    console.log('The following error has occurred:', error);
  } else {
    console.log('Something went horribly wrong.');
  }
});
```