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 = ;
Basic Use
const Halfpenny = ; const myHalfpenny = Halfpenny;
The options are:
authCookieName
<String>
: Authentication cookie’s name. [REQUIRED
]baseUrl
<String>
: Base URL for the API server. [REQUIRED
]storage
<Object>
: Storage instance for persisting authentication credentials. This defaults tolocalStorage
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 endpointauthenticate
<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 ;
Halfpenny#post(endpoint[, data][, authenticate])
endpoint
<String>
: API route’s endpointdata
<String> | <Object>
: Payload to send with the requestauthenticate
<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 ;
Halfpenny#put(endpoint[, data][, authenticate])
endpoint
<String>
: API route’s endpointdata
<String> | <Object>
: Payload to send with the requestauthenticate
<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 ;
Halfpenny#delete(endpoint[, data][, authenticate])
endpoint
<String>
: API route’s endpointdata
<String> | <Object>
: Payload to send with the requestauthenticate
<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 ;
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 = ;const Halfpenny = ;const jQuery = ; const hp = authCookieName: coinsDepositBoxcookieName baseUrl: coinsDepositBoxapiURL storage: localStorage requestEngine: jQueryajax;
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 * @param * @param * @param * @param * @param * @returns */hp { const data = requestOptionsdata; const mappedOptions = method: requestOptionsmethod url: requestOptionsurl ; if requestOptionsheaders mappedOptionsheaders = requestOptionsheaders; if requestOptionswithCredentials mappedOptionsxhrFields = withCredentials: true ; if data if typeof data === 'object' mappedOptionsdataType = 'json'; mappedOptionsdata = 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.