halfpenny

Halfpenny

Official JavaScript client for steelpenny.

Installation

Ensure Node.js (version 6+) and npm are set up on your machine. To install Halfpenny in your project, simply run:

npm install halfpenny --save

This persists Haflpenny to your package.json. You can now use it in your application code:

const Halfpenny = require('halfpenny');

Basic Use

The easiest way to get started with Halfpenny is to use the Halfpenny.factory static method:

const Halfpenny = require('halfpenny');

const myHalfpenny = Halfpenny.factory();

This configures a Halfpenny instance using environment-specific configuration from coins-deposit-box. Alternatively, you can override configuration:

const Halfpenny = require('halfpenny');

const myHalfpenny = Halfpenny.factory({
  baseUrl: 'http://localhost:8800',
});

The options are:

• authCookieName <String>: Authentication cookie’s name.
• baseUrl <String>: Base URL for the API server.
• storage <Object>: Storage instance for persisting authentication credentials. This defaults to localStorage in browsers, or dom-storage in Node.js.

Philosophy

Halfpenny is a minimal, lightweight API client: it exposes the essential functionality required for COINS ecosystem applications. This includes:

• Account creation
• Logging in and logging out
• Persisted authentication via headers
• Password reset

All other required functionality for an application should be placed in application code. Halfpenny exposes methods to assist in API requests.

Methods

Halfpenny#get(endpoint)

• endpoint <String>: API route’s endpoint

Make a HTTP GET request with the specified endpoint to the API. Returns a Promise.

hp.get('/scans')
  .then((response) => {
    const scans = response.data.data;
    console.log('Received scans!', scans);
  })
  .catch((response) => {
    console.error('Request error!', response.error);
  });

Halfpenny#post(endpoint[, data])

• endpoint <String>: API route’s endpoint
• data <String> | <Object>: Payload to send with the request

Make a HTTP POST request with the specified endpoint to the API. Optionally, send data in the request body. Returns a Promise.

hp.post('/scans', {
  label: 'My great scan!',
  segmentInterval: 1,
  studyId: 123,
  scannerId: 5,
  operatorId: 9,
  ursi: 'M123456789',
  // ...
})
  .then((response) => {
    const newScan = response.data.data[0];
    console.log('New scan created!', newScan);
  })
  .catch((response) => {
    console.error('Request error!', response.error);
  });

Halfpenny#put(endpoint[, data])

• endpoint <String>: API route’s endpoint
• data <String> | <Object>: Payload to send with the request

Make a HTTP PUT request with the specified endpoint to the API. Optionally, send data in the request body. Returns a Promise.

hp.put('/scans/123', {
  subjectMass: 120,
  subjectMassUnits: 'LBS',
  subjectAge: 18,
  notes: 'The subject ate a bagel prior to scan',
})
  .then((response) => {
    const updatedScan = response.data.data[0];
    console.log('Scan updated!', updatedScan);
  })
  .catch((response) => {
    console.error('Request error!', response.error);
  });

Halfpenny#delete(endpoint[, data])

• endpoint <String>: API route’s endpoint
• data <String> | <Object>: Payload to send with the request

Make a HTTP DELETE request with the specified endpoint to the API. Optionally, send data in the request body. Returns a Promise.

hp.delete('/scans/123')
  .then((response) => {
    const removedScan = respones.data.data[0];
    console.log('Scan deleted!', removedScan)
  })
  .catch((response) => {
    console.error('Request error!', response.error);
  });

Custom Request Engine

Halfpenny allows you to override the default request engine (axios) with a custom one. Pass it as a parameter on config.requestEngine to the constructor:

const coinsDepositBox = require('coins-deposit-box');
const Halfpenny = require('halfpenny');
const jQuery = require('jquery');

const hp = new Halfpenny({
  authCookieName: coinsDepositBox.cookieName,
  baseUrl: coinsDepositBox.apiURL,
  storage: localStorage,
  requestEngine: jQuery.ajax,
});

Halfpenny uses the private Halfpenny#mapRequestOptions method on every request to transform the request options. Override this method to map arguments to the new request engine:

const cloneDeep = require('lodash/cloneDeep');

hp.mapRequestOptions = (requestOptions) => {
  const opts = cloneDeep(requestOptions);

  delete ops.withCredentials;
  opts.xhrFields = {
    withCredentials: true,
  };

  return opts;
};

Documentation

Run npm run docs to generate API documentation, which is output in the docs directory as webpages.

Development

• Linting: This project adheres to Airbnb’s JavaScript style guide. Run npm run lint to lint the project’s source and test files.
• Testing: This project uses the minimal test framework tape and Sinon.js for spying and stubbing. Run npm test to run the project’s tests.

License

MIT. See LICENSE for details.