lightrail-client

Lightrail Client for JavaScript and TypeScript

Lightrail is a modern platform for digital account credits, gift cards, promotions, and points (to learn more, visit Lightrail). This is a basic library for developers to easily connect with the Lightrail API using Javascript or Typescript. If you are looking for specific use cases or other languages, check out the complete list of all Lightrail libraries and integrations.

Features

The following features are supported in this version:

• Account credits: create, retrieve, balance-check, and create/simulate transactions
• Gift cards: create, retrieve, balance-check, and create/simulate transactions

Note that the Lightrail API supports many other features and we are still working on covering them in this library. For a complete list of Lightrail API features check out the Lightrail API documentation.

Usage

Compiling for node with webpack

This library uses superagent to facilitate network requests. To have webpack use the node-version of superagent your webpack config must include target: 'node'.

If when running your code you see the error TypeError: undefined is not a function then most likely you must include the following in the plugins section of your webpack config: plugins: [new webpack.DefinePlugin({"global.GENTLY": false})]. See https://github.com/felixge/node-formidable/issues/337 for an explanation.

Configuration

Before using this client, you'll need to configure it to use your API key:

const Lightrail = require('lightrail');

Lightrail.configure({
  apiKey: <LIGHTRAIL API KEY>
})

Use Case: Account Credits Powered by Lightrail

The remainder of this document is a quick demonstration of implementing account credits powered by Lightrail using this library. It will assume familiarity with the API and some core concepts, which are discussed in detail in the 'Powering Account Credits' section of the API documentation.

Handling Contacts

Creating a New Contact

To create a new Contact, you need to provide a client-side unique identifier known as the userSuppliedId. The userSuppliedId is a per-endpoint unique identifier used to ensure idempotence. Ensuring idempotence means that if the same request is issued more than once, it will not result in repeated actions. Optionally, you can also provide an email, firstName, and lastName. Here is a sample request:

const Lightrail = require('lightrail');

const newContactParams = {
  userSuppliedId: 'customer-9f50629d',
  email: '[e-mail]',
  firstName: 'Test',
  lastName: 'McTest'
};
Lightrail.createContact(newContactParams).then(
  // called asynchronously
);

Sample response:

{
  "contactId": "contact-271a",
  "userSuppliedId": "customer-9f50629d",
  "email": "[e-mail]",
  "firstName": "Test",
  "lastName": "McTest",
  "dateCreated": "2017-07-26T23:50:04.000Z"
}

The response objects will include both the userSuppliedId and a server-generated contactId which you can persist and use to retrieve the Contact later.

Retrieving a Contact

You can retrieve a Contact based on its contactId. The response to this call will be a contact object similar to the one shown above.

Lightrail.contacts.getContactById('contact-271a').then(
  // called asynchronously
);

Alternatively, you can retrieve a contact based on its userSuppliedId:

Lightrail.contacts.getContactByUserSuppliedId('customer-9f50629d').then(
  // called asynchronously
);

Handling Accounts

Creating Accounts

You can create an account for a contact based on their contactId (generated by Lightrail) or based on their shopperId (an identifier generated by your e-commerce system). You must also specify the currency that the account will be in, and provide auserSuppliedId, a unique identifier from your own system. Since each Contact can have only up to one Account Card per currency, you can add the currency as a suffix to the userSuppliedId you provided for the Contact. You may optionally include an initialValue for the account.

const newAccountParams = {
  userSuppliedId: 'customer-9f50629d-USD',
  cardType: 'ACCOUNT_CARD',
  currency: 'USD',
  initialValue: 500,
};
Lightrail.contacts.accounts.createAccount({shopperId: 'customer-9f50629d'}, newAccountParams).then(
  // called asynchronously
);

The response object will include both the userSuppliedId and a server-generated cardId which you can persist and use to retrieve the Account Card later.

{
  "cardId": "card-1dxxea",
  "userSuppliedId": "customer-9f50629d-USD",
  "contactId": "contact-271a",
  "dateCreated": "2017-07-26T23:50:04.572Z",
  "cardType": "ACCOUNT_CARD",
  "currency": "USD",
  "categories":[
    {
      "categoryId": "category-bdxx88",
      "key": "giftbit_order",
      "value": "2017-07-26"
    },
    {
      "categoryId": "category-95xxc2",
      "key": "giftbit_program",
      "value": "program-account-USD-user-088e"
    }
  ]
}

Funding and Charging

To fund or charge an account, you can once again use either the contactId (generated by Lightrail) or the shopperId (generated by your e-commerce system) to identify the customer account that you wish to transact against.

You must additionally pass in the following:

• The value of the transaction: a positive value will add funds to the account, while a negative value will post a charge to the account. This amount must be in the smallest currency unit (e.g., 500 for 5 USD)
• The currency that the transaction is in (note that Lightrail does not handle currency conversion and the contact must have an account in the corresponding currency)
• A userSuppliedId, which is a unique transaction identifier to ensure idempotence (for example, the order ID from your e-commerce system)

const transactionParams = {
  value: 1200,
  currency: 'USD',
  userSuppliedId: 'tx-fe2d'
};
Lightrail.contacts.accounts.createTransaction({shopperId: 'customer-9f50629d'}, transactionParams).then(
  // called asynchronously
);

The returned object includes both the userSuppliedId and a server-generated transactionId which you can use later to retrieve this transaction.

{
  "transactionId": "transaction-fec7",
  "value": 1200,
  "userSuppliedId": "tx-fe2d",
  "dateCreated": "2017-07-27T23:51:12.228Z",
  "transactionType": "FUND",
  "transactionAccessMethod": "CARDID",
  "cardId": "card-1dea",
  "currency": "USD"
}

Transaction Simulation and Balance Checking

Before attempting to post a transaction, you may wish to do a transaction simulation to find out whether or not the account has enough funds. In the case of insufficient funds, this can also tell you the maximum value for which the transaction would be successful. For example, if you simulate a $35 drawdown Transaction, the method can tell you that it would be successful if it were only for $20.

The parameters for this method call are almost identical to those for posting a transaction. To get the maximum value, add nsf: false to your transaction parameters:

const simulationParams = {
  value: -6960,
  currency: 'USD',
  userSuppliedId: 'order-s3xx30',
  metadata: {
    cart: {
      total: 6960,
      items: [{
        quantity: 3,
        id: 'B009L1MF7A',
        unit_price: 2320
      }]
    }
  }
};
Lightrail.contacts.accounts.simulateTransaction({shopperId: 'customer-9f50629d'}, simulationParams).then(
  // called asynchronously
);

The response will be similar to the following. Note that this is just a simulation and NOT an actual transaction; for instance, it does not have a transactionId. The response indicates that for this transaction, the maximum value this account can provide is $55.

{
  "value":-5500,
  "userSuppliedId":"order-s3xx30",
  "dateCreated":null,
  "transactionType":"DRAWDOWN",
  "transactionAccessMethod":"CARDID",
  "valueAvailableAfterTransaction":0,
  "cardId":"card-dcxx37",
  "currency":"USD",
  "transactionBreakdown":[
    {
      "value":-500,
      "valueAvailableAfterTransaction":0,
      "valueStoreId":"value-02xx6c"
    },
    {
      "value":-5000,
      "valueAvailableAfterTransaction":0,
      "valueStoreId":"value-66xxf2"
    }
  ],
  "transactionId":null,
  "metadata":{
    "cart":{
      "total":6960,
      "items":[
        {
          "quantity":3,
          "id":"B009L1MF7A",
          "unit_price":2320
        }
      ]
    }
  },
  "codeLastFour":"YNJC"
}

Testing

IMPORTANT: note that several environment variables are required for the tests to run. After cloning the repo, npm install dependencies and set the following (either in a .env file in the root directory or however you prefer to set environment variables):

• LIGHTRAIL_API_KEY: find this in to the Lightrail web app -- go to your account settings, then click 'API keys' and 'Generate Key.' Note that for running tests, you should use a test mode key.

• CARD_ID: this is the cardId for a USD card with at least a few dollars on it.

• SHOPPER_ID: the userSuppliedId for a Lightrail contact with a USD account

• CONTACT_ID: the Lightrail-generated contactId for the same contact

Then you can run npm test.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Giftbit/lightrail-client-javascript.

License

This library is available as open source under the terms of the MIT License.