Skip to content

Latest commit

 

History

History
204 lines (140 loc) · 7.77 KB

README.md

File metadata and controls

204 lines (140 loc) · 7.77 KB
Raw

RewardOps Node SDK

npm version Build status npm bundle size (scoped) Node support license Conventional commits

The RewardOps Node SDK dramatically simplifies OAuth as well as typical interfacing with our public APIs. Simply add your clientId and clientSecret to the config and you're ready to go.

Note: The SDK currently supports v4 and v3 of the RewardOps API. In addition, v5 endpoints are partially implemented.

Installation

NPM

To use the SDK in your Node.js project:

npm install @rewardops/sdk-node

To install and save a specific (legacy) version of the SDK in your package.json, use a version tag in the Git URL:

npm install --save git+ssh://[email protected]:rewardops/rewardops-sdk-node.git#v0.4.6

Usage

Configuration

The following properties must be set before making any API calls using the SDK:

  • clientId: Your RewardOps API OAuth client_id.
  • clientSecret: Your RewardOps API OAuth client_secret.

For example, in your application initialization module, you can add:

const RO = require('rewardops-sdk');

RO.config.init({
  ...restOfConfig,
  clientId: 'abcdefg1234567',
  clientSecret: '9876543poiuytr',
});

NOTE: If your program is configured to use geographic-specific PII storage, you must also set:

  • piiServerUrl: Geographic-specific PII storage server URL.
  • supportedLocales: List of accepted locales for the program (RFC2616 format).
RO.config.init({
  ...restOfConfig,
  piiServerUrl: 'https://api.ca.rewardops.net',
  supportedLocales: ['en-CA', 'en-FR'],
});

See the config module in the SDK library documentation for all config options.

Environment variables

NOTE RO.config.set has been deprecated in favor of RO.config.init which requires all the configuration values at initialization.

To change the RewardOps host API URL, you can optionally set the environment variable REWARDOPS_ENV before starting your application. (See the api module of the library documentation for more info.)

Overview

When you make a call to the API using the SDK, the SDK will automatically use an existing valid bearer token if it has already received one. Otherwise, it will request one from the API and cache it for further use.

Several SDK methods can receive options objects, which then passed directly to the RewardOps API calls. Available parameters can be viewed on RewardOps API console. As a rule, path parameters (e.g., required program, reward, and order IDs) are passed as the first argument to SDK methods, while other parameters should appear in an options object.

In addition, most methods accept a callback function, whose type definition can be found in the api module of the library documentation.

Example methods

Programs

// Get a list of all programs available to you
RO.programs.getAll(callback);

// Get details of a program
RO.programs.get(123, callback);

Program

The program object has methods for accessing the program's rewards, orders, and more:

//  Return a program object for the program with the specified `id`
const myProgram = RO.program(123); // Standard program
const myProgram = RO.program(123, 'example_program_code'); // Geographic-specific PII storage-enabled program

// Get details for program 123
// Alias of `RO.programs.get(123)`
myProgram.details(callback);

// Get a list of all orders for a member in a program
// NOTE: The `options` object is required and must include a `member_id`.
myProgram.orders.getAll(options, callback)
// Gets the order with ID 'qwerty1234'
myProgram.orders.get('qwerty1234' callback);
// Post a new order for the reward with id 45231 for member 'bbdd0987'
// NOTE: The `options` object is required and must include a `reward_id` and a `member` object
myProgram.orders.create(
  {
    member: {
      id: 'jb0987',
      full_name: 'Jolanta Banicki',
      email: '[email protected]',
    },
  },
  callback
);

// Get JSON for the customCategory with code CAT_000002
myProgram.customCategories.get('CAT_000002', callback);

// Get JSON for the item with ID 938
myProgram.items.get(938, callback);

This is a subset of the available methods. For the complete SDK API, see the library documentation.

Example usage

For examples of the SDK in use, see the examples/ directory.

Maintainer

Shane Martin <[email protected]>

Contributing

NOTE: This section is for developers maintaining the rewardops-sdk-node library, rather than those consuming the npm package.

This repository uses semantic versioning, conventional commits and the standard-version library for versioning and changelog documentation. Ensure that you are familiar with those before contributing.

Use nvm or check .nvmrc for expected Node version.

Install:

npm install

Developing with an application:

Use npm link

  1. run npm link in the directory of the SDK. This will create a symlink with the global npm folder.
npm link
  1. run npm link @rewardops/sdk-node in the directory of your app. This will create a symlink from the global npm folder to your app.
npm link @rewardops/sdk-node

Running Locally

Right now there is no way for this to run locally, because this project does not act as a server or something similar. One way to test your changes are correct are not are writing unit tests in their respective folders, for example if you added a new resource, you can add a test inside test / resources / ${api_version_resource uses} / ${resouce}.js file. You can then debug that in VS Code, the configuration is already added, you just have to update the first argument of the args array inside launch.json, change that to the name of the test file that you want to run and it will start debug with real values just to verify, after that you can mock the values when commiting your code.

NOTE There is no hot reloading, if you make code changes to the SDK, you will have to re-run step 2 for you changes to appear in your app. Running yarn install will also remove the symlink.

To run the library test suite:

npm test

To build the documentation locally:

npm run build:docs

To publish a new version, run:

git checkout master
git pull
npm run release -- --dry-run # note outputted version number
git checkout -b release/[outputted version]
npm run release
# review CHANGELOGS for accuracy
git push --set-upstream origin release/[outputted version]
# create a PR
# once approved, merge PR into master
git checkout master
git pull
npm test && npm publish && npm run publish:docs