@cargochain/sdk-js/README.md

The CargoChain platform allows application developers to build supply chain solutions that enable the secure distribution of cargo information among trusted partners.

CargoChain’s API is 100% accessible over a set of HTTPS REST calls using the widespread
JSON format, making CargoChain open to any other Internet-capable technology.

In order to simplify the integration of your applications with CargoChain, we provide an Enterprise SDK in different development languages.

# Installation
The JS SDK client is available as a [NPM package](https://www.npmjs.com/package/@cargochain/sdk-js).
```
$ npm i @cargochain/sdk-js
$ npm i --save @cargochain/sdk-js
```

# Usage
The main object is ``CargoChainClient`` singleton. You have to specify the URL of the CargoChain API by using the ``setUrl()`` function. [See the CargoChain locations](https://github.com/CargoChain/doc/wiki#locations).

The ``CargoChainClient`` instance has two properties that allow to interact with the CargoChain API:
- ``profile``: exposes the functions for manipulating profiles (create profiles, search profiles, add events, set metadata, etc). [See the CargoChain API for profiles](https://github.com/CargoChain/doc/wiki/V2-API).
- ``referenceData``: exposes the functions for getting all reference data natively provided by CargoChain (Countries, Currencies, HS Codes, UN/LOCODE, etc).

## API Result
The result of each API call has the following format:
``` javascript
{
    isSuccess,          // true / false if the call is success
    message,            // if isSuccess if false, this property contains an error message
    statusCode,         // the HTTP status code
    data,               // the data returns by the CargoChain API
    page                // the information for the pagination (https://github.com/CargoChain/doc/wiki/V2-API#pagination) if the endpoint supports it
}
```

## Security
You have to specify an Access Token to the ``CargoChainClient`` instance in order to perform the calls to the CargoChain API. For more details, [see the API Authentication](https://github.com/CargoChain/doc/wiki/V2-Authentication).

To set the Access Token to the ``CargoChainClient`` instance, you have to use the ``setAccessToken()`` function.

If the CargoChain API returns an authentication error, you can handle it by using the ``setOnAccessTokenExpiredHandler()`` function. The handler that you have to specify by calling this function should ask for a new Access Token (typically by calling the CargoChain Portal) and set again the Access Token by using the ``setAccessToken()`` function.

# Example
``` javascript
// Load the CargoChainClient
const CargoChainClient = require('@cargochain/sdk-js');

// Get the instance
const client = CargoChainClient.instance;
// Set the CargoChain API Url 
client.setUrl('https://api2-tests.cargochain.com');
// Set your access token
client.setAccessToken('[MY ACCESS TOKEN]');

client.setOnAccessTokenExpiredHandler(() => {
    // Here you should call the CargoChain Portal in order to get a new access token
    const token = "[MY NEW ACCESS TOKEN]";
    client.setAccessToken(token);
});

client.referenceData.getCountries().then((res) => {
    // Display the number of countries
    console.log(res.data.length);
});

client.profile.getAllProfiles(5).then((res) => {
    // ...
});
```