Ambrosus SDK

Library for simple interaction with Ambrosus API.

Contribution

Please refer to project's code style guidelines and guidelines for submitting patches and additions. In general, we follow the "fork-and-pull" Git workflow.

Fork the repo on GitHub
Clone the project to your own machine
Commit changes to your own branch
Push your work back up to your fork
Submit a Pull request so that we can review your changes

NOTE: Be sure to merge the latest from "upstream" before making a pull request!

It is mandatory to follow our code of conduct described in CONTRIBUTING.md.

Prerequisite

In order to use Ambrosus SDK, first you need to have a developers account.
You can apply for one here.

Ambrosus team will send you an email with your account address and secret key.

Important note: PLEASE DO NOT SHARE YOUR SECRET WITH ANYONE.
We do not store your secret for security reasons, so please save it somewhere safe, in order to use it in SDK.

To use Ambrosus SDK, you will need your address and secret key.
Now we can go to setup.

Setup

npm

$ npm install ambrosus-javascript-sdk --save

Import the SDK in your javascript file

const AmbrosusSDK = require('ambrosus-javascript-sdk');

Download

Directly download the library and host it locally.
You can download library here.

If your project structure is for example:

project-name/js/ambrosus.min.js
project-name/index.html

You would include it in your index.html where you use Ambrosus SDK like:

<script async src="/js/ambrosus.min.js"></script>

Usage

Initialize the Ambrosus library.
In the script on your page where you use Ambrosus SDK, put this code in the beginning of the script:

var ambrosus = new AmbrosusSDK({
  // Provide env variables
  secret: '0x6823520c03ad7b17bc1a7144fbbd2d24bfa2ce933d715ace209d658e03fdd388',
  address: '0x6c06dD0215d4eef9E795C0b5BwED697a26287aFB'
});

Variable	Type	Definition	Example
secret	string	Secret key you received in email.	0x6c06dD0215d4eef9E795C0b5BwED697a26287aFB
address	string	Address you received in email.	0x6823520c03ad7b17bc1a7144fbbd2d24bfa2ce933d715ace209d658e03fdd388

Each state-modifying call needs to have the secret and address values. If you wish to use the SDK only to request or query the data, You can initialise the SDK like -

var ambrosus = new AmbrosusSDK({
  apiEndpoint: 'https://gateway-test.ambrosus.com'
});

Variable	Type	Definition	Example
secret	string	Secret key you received in email.	0x6c06dD0215d4eef9E795C0b5BwED697a26287aFB
address	string	Address you received in email.	0x6823520c03ad7b17bc1a7144fbbd2d24bfa2ce933d715ace209d658e03fdd388

Response from Ambrosus SDK methods

Every Ambrosus SDK method (examples below), will return the response with this structure:

Response type: object

{
  "status": 404,
  "data": null,
  "message": "Entity not found: No event with id = null found"
}

Property	Type	Definition	Example
status	number	Http response code	200, 404
data	object	Data returned from the SDK	JSON response data (examples below) or null (if error)
message	string	Message describing the response	Entity not found: No event with id = null found

Events

Library supports internal events.

ambrosus.on('asset:created', function() {
  // your method here
});

Ambrosus SDK methods

Assets

GET asset

Returns the data of a specific asset.

Parameter	Requirement	Type	Definition	Example
assetId	required	string	Asset's ID	0xc0cdb3f2b81d928369de4143cdb1a20e5ecdec09e0ea123dd828bdcc55a048db

ambrosus.getAssetById(assetId).then(function(response) {
  // Response if successful
  console.log(response);
}).catch(function(error) {
  // Error if error
  console.log(error);
});

Response example for GET asset:

{
  "status": 200,
  "data": {
    "assetId": "0xc5cfd04.....30755ed65",
    "content": {
      "signature": "0x30755ed65396facf86c53e6...65c5cfd04be400",
      "idData": {
        "createdBy": "0x162a44701727a31f457a53801cd181cd38eb5bbd",
        "timestamp": 1503424923,
        "sequenceNumber": 3
      }
    },
    "metadata": {
      "bundleId": "0x85a427a3.....cd1d38ebbd",
      "bundleTransactionHash": "0x21ab....1cdf8e55b37"
    }
  },
  "message": "success"
}

Error example for GET asset. Reasons:

If in the setup, address and secret are incorrect.
If assetID doesn't exist.
If you don't have permission to access the asset.

{
  "status": 404,
  "data": null,
  "message": "No asset with such assetId found"
}

GET assets

Returns array of assets.
For this method you can apply certain filters, to get ie. first 20 assets.

Parameters:

Parameter	Requirement	Type	Definition	Example
options	optional	object	Options (below)	Example below

Options (filters):

Parameter	Requirement	Type	Definition	Example
perPage	optional	number	Number of assets to return per page	20

    const options = {
        "perPage": 1
    }

    ambrosus.getAssets(options).then(function(response) {
      // Response if successful
      console.log(response);
    }).catch(function(error) {
      // Error if error
      console.log(error);
    });

Response example for GET assets:

{
  "status": 200,
  "data": {
    "results": [
      {
        "assetId": "0xc5cfd04.....30755ed65",
        "content": {
          "signature": "0x30755ed65396facf86c53e6...65c5cfd04be400",
          "idData": {
            "createdBy": "0x162a44701727a31f457a53801cd181cd38eb5bbd",
            "timestamp": 1503424923,
            "sequenceNumber": 3
          }
        },
        "metadata": {
          "bundleId": "0x85a427a3.....cd1d38ebbd",
          "bundleTransactionHash": "0x21ab....1cdf8e55b37"
        }
      }
    ],
    "resultCount": 53
  },
  "message": "success"
}

Error example for GET assets.
In this case, if you don't have any assets, you will receive status of 200, but in the data, data.results will be empty array, as well as data.resultCount will be 0.

{
  "status": 200,
  "data": {
    "results": [],
    "resultCount": 0
  },
  "message": ""
}

CREATE asset

Create new asset.

Parameters:

Parameter	Requirement	Type	Definition	Example
assetData	required	object	Asset data information	Example below

Example for assetData:

    [
      {
        "type": "ambrosus.asset.info",
        "name": "PURE DARK CHOCOLATE BAR 92%",
        "images": {
          "default": {
            "url": "http://imageurlgoeshere.com/file.extension"
          }
        },
        "size": "2.64 oz.",
        "Product Information": {
          "attributes": "No-GMOs, Vegan, Gluten Free, Kosher, Soy Free",
          "ingredients": "Organic cocoa beans, organic sugar, organic cocoa butter",
          "Brand": "Madecasse"
        },
        "Batch Information": {
          "Origin": "Madagascar"
        }
      }
    ];

This will first create an asset in the background of SDK, then on success it will create a first following event. It's important that event type ends with .info, all other information in example above is customizable.

ambrosus.createAsset(assetData).then(function(response) {
  // Response if successful
  console.log(response);
}).catch(function(error) {
  // Error if error
  console.log(error);
});

Response example for GET asset:

{
  "status": 200,
  "data": {
    "assetId": "0xc5cfd04.....30755ed65",
    "content": {
      "signature": "0x30755ed65396facf86c53e6...65c5cfd04be400",
      "idData": {
        "createdBy": "0x162a44701727a31f457a53801cd181cd38eb5bbd",
        "timestamp": 1503424923,
        "sequenceNumber": 3
      }
    }
  },
  "message": "success"
}

Error example for CREATE asset. Reasons:

If in the setup, address and secret are incorrect.

{
  "status": 403,
  "data": null,
  "message": "The createdBy user is not registered or has no "create_entity" permission"
}

Events

GET event

Returns the data of a specific event.

Parameter	Requirement	Type	Definition	Example
eventId	required	string	Event's ID	0xc0cdb3f2b81d928369de4143cdb1a20e5ecdec09e0ea123dd828bdcc55a048db

ambrosus.getEventById(eventId).then(function(response) {
  // Response if successful
  console.log(response);
}).catch(function(error) {
  // Error if error
  console.log(error);
});

Response example for GET event:

{
  "status": 200,
  "data": {
    "eventId": "0xc5cfd04.....30755ed65",
    "content": {
      "signature": "0x30755ed65396facf86c53e6...65c5cfd04be400",
      "idData": {
        "assetId": "0xc5cfd04.....30755ed65",
        "createdBy": "0x162a44701727a31f457a53801cd181cd38eb5bbd",
        "accessLevel": 4,
        "timestamp": 1503424923,
        "dataHash": "0x01cd181cd38eb5bbd162a44701727a31f457a538"
      },
      "data": [
        {
          "type": "ambrosus.event.customevent",
          "customField": "customValue"
        }
      ]
    }
  },
  "message": "success"
}

Error example for GET event. Reasons:

If event with eventId doesn't exist.

{
  "status": 404,
  "data": null,
  "message": "Event not found"
}

GET events

Returns array of events.
For this method you can apply certain filters, to get ie. all events for a specific assetId.

Parameters:

Parameter	Requirement	Type	Definition	Example
options	optional	object	Options (below)	Example below

Options (filters):

Parameter	Requirement	Type	Definition	Example
assetId	optional	string	Asset's ID	0xc0cdb3f2b81d928369de4143cdb1a20e5ecdec09e0ea123dd828bdcc55a048db
fromTimestamp	optional	number	Earliest timestamp (date in seconds)	1503424923
toTimestamp	optional	number	Latest timestamp (date in seconds)	1503424923
perPage	optional	number	Number of assets to return per page	20
data	optional	string	Filter events by object properties in event.content.data array	data[type]=ambrosus.event.info

    const options = {
        "assetId": "0xc0cdb3f2b81d928369de4143cdb1a20e5ecdec09e0ea123dd828bdcc55a048db",
        "fromTimestamp": 1503424723,
        "toTimestamp": 1503424923,
        "perPage": 5,
        "data": "data[type]=ambrosus.event.info"
    }

    ambrosus.getEvents(options).then(function(response) {
      // Response if successful
      console.log(response);
    }).catch(function(error) {
      // Error if error
      console.log(error);
    });

Response example for GET events:

{
  "status": 200,
  "data": {
    "results": [
      {
        "eventId": "0xc5cfd04.....30755ed65",
        "content": {
          "signature": "0x30755ed65396facf86c53e6...65c5cfd04be400",
          "idData": {
            "assetId": "0xc5cfd04.....30755ed65",
            "createdBy": "0x162a44701727a31f457a53801cd181cd38eb5bbd",
            "timestamp": 1503424923,
            "dataHash": "0x01cd181cd38eb5bbd162a44701727a31f457a538"
          },
          "data": [
            {
              "type": "ambrosus.event.customevent",
              "customField": "customValue"
            }
          ]
        }
      }
    ],
    "resultCount": 112
  },
  "message": "success"
}

Error example for GET events.
Reasons:

No events with provided options.

{
  "status": 404,
  "data": null,
  "message": "Event not found"
}

CREATE event

Create new event.

Parameters:

Parameter	Requirement	Type	Definition	Example
assetId	required	string	Asset's ID	0xc0cdb3f2b81d928369de4143cdb1a20e5ecdec09e0ea123dd828bdcc55a048db
eventData	required	object	Event data information	Example below

Example for eventData:

    [
      {
        "type": "ambrosus.asset.info",
        "name": "PURE DARK CHOCOLATE BAR 92%",
        "assetType": "ambrosus.assetTypes.batch",
        "images": {
          "default": {
            "url": "http://imageurlgoeshere.com/file.extension"
          }
        },
        "size": "2.64 oz.",
        "Product Information": {
          "attributes": "No-GMOs, Vegan, Gluten Free, Kosher, Soy Free",
          "ingredients": "Organic cocoa beans, organic sugar, organic cocoa butter",
          "Brand": "Madecasse"
        },
        "Batch Information": {
          "Origin": "Madagascar"
        }
      }
    ];

ambrosus.createEvent(assetId, eventData).then(function(response) {
  // Response if successful
  console.log(response);
}).catch(function(error) {
  // Error if error
  console.log(error);
});

Response example for CREATE event:

{
  "status": 200,
  "data": {
    "eventId": "0xc5cfd04.....30755ed65",
    "content": {
      "signature": "0x30755ed65396facf86c53e6...65c5cfd04be400",
      "idData": {
        "assetId": "0xc5cfd04.....30755ed65",
        "createdBy": "0x162a44701727a31f457a53801cd181cd38eb5bbd",
        "accessLevel": 4,
        "timestamp": 1503424923,
        "dataHash": "0x01cd181cd38eb5bbd162a44701727a31f457a538"
      },
      "data": [
        {
          "type": "ambrosus.event.customevent",
          "customField": "customValue"
        }
      ]
    }
  },
  "message": "success"
}

Error example for CREATE event. Reasons:

If in the setup, address and secret are incorrect.

{
  "status": 400 or 403,
  "data": null,
  "message": "Invalid input" or "The createdBy user is not registered or has no "create_entity" permission"
}

Examples

See examples/ for working examples of how the SDK can be used.

lkieliger / sdk-javascript

Ambrosus SDK

Contribution

Overview

Prerequisite

Setup

npm

Download

Usage

Response from Ambrosus SDK methods

Events

Ambrosus SDK methods

Assets

GET asset

GET assets

CREATE asset

Events

GET event

GET events

CREATE event

Examples

About

Languages