Nuts API NodeJS Client

This repository holds a library written in NodeJS to help consume the Nuts API in order to access resources from the Livello platform, such as fridges, users, product items, transactions or payment methods.

This library perform queries against the API on behalf of users, authenticated using third party OAuth 2 providers, and therefore it is suitable to be used on client applications that cannot keep secrets.

Installation

You can install this package using NPM private git dependencies: npm install --save git+ssh://[email protected]:livello-smart-fridges/nuts-nodejs.git

Alternatively, you can pin to a specific version by appending #<version-name> to the git URL.
Note: You need to have SSH access to this repository prior to installing the package.

Usage

This client exposes authenticated access only, and hence it needs an identity to operate.
You can instantiate and API object in two different ways:

Authenticating a New User

To authenticate a specific user you can use the authenticate method, exposed statically. This method returns a promise, containing the API object ready to be used:

var NutsApi = require('nuts-nodejs');
var myApi;
NutsApi.authenticate(idToken, accessToken, provider).then(({ api, token }) => myApi = api);

where idToken and accessToken are those provider by the OAuth authentication provider, and provider is the key that identifies it (eg.: google).

Reusing an Existing Token

Alternatively, you can directly instantiate an API object using a JWT token that was previously generated by the API and stored accordingly:

var NutsApi = require('nuts-nodejs');
var api = new NutsApi(<jwt-token>);

Accessing Resources

All requests and calls to the API are executed and exposed using promises. Requests that fail to deserialize or respond with an error HTTP status code will cause the promise to fail. For example, to add a new payment method:

api.paymentMethods.create({source: 'src_1CAEAPKsKLCD8MyXqpAPteJ4'})
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

Or, to obtain a list of fridges visible to the currently authenticated user:

api.fridges.list()
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

Results: Response and Error

Successfully fulfiled promises return an object that contains the status code and the contents of the response. For the previous example, a successful call to the list of fridges yields the following response object:

{
    "status": 200,
	"body": [{
	    "id": 7,
        "created": "2018-03-09T19:37:48Z",
		"modified": "2018-03-13T14:09:04Z",
        "items": {
            "total": 5,
            "expired": 1
        },
		...
	},
	{...}]
}

Errorring requests can be catched as a failed promise, containing the expected error object. Prior to throwing, this object is appended a body that holds more detail about the cause of the failure.

Resources

Resources are exposed using modules attached to the API object. These modules conform to a similar structure and operation, by exposing CRUD-like methods (create, list, get, update, delete) that allow interaction with the with the corresponding resources.

The set of resources currently exposed in this client library is the following:

Resource Name | Path | Available Methods | --------------- | ------------------ | ---------------------------------------------------------------------- | Fridges | api.fridges | list(), get(id), buy(id) | Current User | api.me | get(), update(userData), delete() | Transactions | api.transactions | list(), get(id), update(id, productIds), checkout(id) | Payment Methods | api.paymentMethods | create(paymentMethodData), list(), set_default(id), delete(id) |