Library for simple interaction with Ambrosus API.
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.
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.
$ npm install ambrosus-javascript-sdk --save
Import the SDK in your javascript file
const AmbrosusSDK = require('ambrosus-javascript-sdk');
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>
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 |
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 |
Library supports internal events.
ambrosus.on('asset:created', function() {
// your method here
});
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"
}
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 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"
}
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"
}
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 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"
}
See examples/ for working examples of how the SDK can be used.