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[, authenticate])

• endpoint <String>: API route’s endpoint
• authenticate <Boolean>: Send authentication headers with the request. Default = false.

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][, authenticate])

• endpoint <String>: API route’s endpoint
• data <String> | <Object>: Payload to send with the request
• authenticate <Boolean>: Send authentication headers with the request. Default = false.

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][, authenticate])

• endpoint <String>: API route’s endpoint
• data <String> | <Object>: Payload to send with the request
• authenticate <Boolean>: Send authentication headers with the request. Default = false.

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][, authenticate])

• endpoint <String>: API route’s endpoint
• data <String> | <Object>: Payload to send with the request
• authenticate <Boolean>: Send authentication headers with the request. Default = false.

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:

/**
 * Map request options.
 *
 * @param {Object} requestOptions
 * @param {Object} requestOptions.headers
 * @param {string} requestOptions.method
 * @param {string} requestOptions.url
 * @param {booleam} requestOptions.withCredentials
 * @param {(string|Object)} [requestOptions.data]
 * @returns {Object}
 */
hp.mapRequestOptions = (requestOptions) => {
  const data = requestOptions.data;
  const mappedOptions = {
    method: requestOptions.method.toUpperCase(),
    url: requestOptions.url,
  };

  if (requestOptions.headers) {
    mappedOptions.headers = requestOptions.headers;
  }

  if (requestOptions.withCredentials) {
    mappedOptions.xhrFields = {
      withCredentials: true,
    };
  }

  if (data) {
    if (typeof data === 'object') {
      mappedOptions.dataType = 'json';
    }

    mappedOptions.data = data;
  }

  return mappedOptions;
};

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.