Primas-sdk-nodejs NPM

Primas-nodejs-sdk

Primas sdk for Node env

Install

  npm install primas-sdk-nodejs --save

Compatibility

Node.js >= 8.0.0 required.

Prerequisite

You should have keystore in your workspace. As an alternative, you can provide the keystore option in the constructor config. All numbers are treated as big number, you should use bignumber.js to deal with it.

Summary

Basic Usage

All operation use nodejs callback. All api is async function.

for example:

  var Primas = require('primas-sdk-nodejs');
  var client = new Primas({
    address: "<Your address>",
    passphrase: "<Your password>"
  })
  client.Account.metadata({accountId: '<account id>'}, function (err, res) {
    if (err) {
      // handle error
      return;
    }
    // handle res
  })

  // for method without callback, you should explicitly call send after sign
  var account = client.Account.create(
      {
          name: "<account name>",
          creator: {
              account_id: "<root account id>", // The platform ID we received in the previous step.
              sub_account_id: "<user id on the platform>" // This id is used together to identify the user on Primas network.
          },
          extra: {
              hash: "<a hex string>" // In case of sensitive user data that needs proof-of-existence, the data hash can be stored here.
          }
      }
  );
  account.send(function(err, res) {
      if (err) {
          // handle error
          return;
      }
      
      // For sub accounts. No account id is returned at the moment.
      // The sub account is identified user root account id and user id on the platform.
      // console.log(res.id);
      
      console.log(res.dna);
  })

Metadata Sign

if you place a folder named "keystore" in your project or you pass a keystore option in constructor, this sdk will use the build-in signer to sign metadata. for production usage, you should implement a Primas Offline Signer instead of the build-in signer. for example:

// here we pass the passphrase and use the build-in signer
var client = new Primas({
	address: "<Your address>",
	passphrase: "<Your password>", 
	node: "https://rigel-a.primas.network"
});

var account = client.Account.create(
	{
		name: "<account name>",
		// avatar: "", // Avatar should be a metadata ID which can only be uploaded after the account creation.
		address: "<account address>"
	});
// if your have keystore in your workspace, just send
account.send(function(err, res) {
    
	if (err) {
		// handle error
		return;
	}
	
	// The response contains the account id and metadata dna
})

// here we don't pass the passphrase because the signer you should implement on your self
var client = new Primas({
	address: "<Your address>",
	node: "https://rigel-a.primas.network"
});

var account = client.Account.create({
  name: "<account name>",
  // avatar: "", // Avatar should be a metadata ID which can only be uploaded after the account creation.
  address: "<account address>"
});

var dataJson = account.getRawMetadata(); 
// do sign now, this sign method is your own offline signer exposed
var signature = sign(dataJson); // this will return signature
// after sign
account.setSignature(signature);
// then send, like the above
account.send(...);

Create A Primas Instance

use Primas constructor to create instance.

options:

node string node url
address {string} your address with '0x' prefix
passphrase string your passphrase, if not provide, you shoud use signer on your own
keystorePath string you can specify the dir of your keystore
keystore string the keystore string or object
json boolean use application/json or not

example:

  var Primas = require('primas-sdk-nodejs');
  var client = new Primas({
    address: "<Your address>",
    passphrase: "<Your password>",
    keystore: "key store object or string" // if this option is not provide, sdk will find keystore in the workspace
  })

Operations

all the callback parameter is a standard nodejs async callback function. It means the first param of the callback is an error object, and the second param is the response data. You should handle the error properly.

Account

.metadata(params, callback)

Get account metadata

parameters:

params {object}
- accountId {string}
- subAccountId {string}

.addressMetadata(address, callback)

Get main account metadata by address

parameters:

address {string}

.create(params)

Create account

parameters:

params {object} the object detail can be find in this page

.update(accountId, params)

Update account

parameters:

accountId {string}
params {object} the object detail can be find in this page

.credits(params, callback)

Get account credits list

parameters:

params {object}
- accountId {string}
- subAccountId {string}

.contents(params, callback)

Get account content list

parameters:

params {object}
- accountId {string}
- subAccountId {string}
- qs {object}
  - page {number} Page number. Starts from 0.
  - page_size {number} Page size. Default to 20.

.groups(params, callback)

Get account groups list

parameters:

params {object}
- accountId {string}
- subAccountId {string}
- qs {object}
  - page {number} Page number. Starts from 0.
  - page_size {number} Page size. Default to 20.

.shares(params, callback)

Get account shares

parameters:

params {object}
- accountId {string}
- subAccountId {string}
- qs {object}
  - page {number} Page number. Starts from 0.
  - page_size {number} Page size. Default to 20.
  - application_status {string} Status filter. "pending", "approved" or "declined".

.sharesInGroup(params, callback)

Get account shares in a single group

parameters:

params {object}
- accountId {string}
- subAccountId {string}
- qs {object}
  - page {number} Page number. Starts from 0.
  - page_size {number} Page size. Default to 20.
  - application_status {string} Status filter. "pending", "approved" or "declined".

.likes(params, callback)

Get account likes

parameters:

params {object}
- accountId {string}
- subAccountId {string}
- qs {object}
  - page {number} Page number. Starts from 0.
  - page_size {number} Page size. Default to 20.

.comments(params, callback)

Get account comments

parameters:

params {object}
- accountId {string}
- subAccountId {string}
- qs {object}
  - page {number} Page number. Starts from 0.
  - page_size {number} Page size. Default to 20.

.groupApplications(params, callback)

Get account group applications

params {object}
- accountId {string}
- subAccountId {string}
- qs {object}
  - page {number} Page number. Starts from 0.
  - page_size {number} Page size. Default to 20.
  - application_status {string} Status filter. "pending", "approved" or "declined".

.shareApplications(params, callback)

Get account share applications

params {object}
- accountId {string}
- subAccountId {string}
- qs {object}
  - page {number} Page number. Starts from 0.
  - page_size {number} Page size. Default to 20.
  - application_status {string} Status filter. "pending", "approved" or "declined".

.reports(params, callback)

Get account report list

params {object}
- accountId {string}
- subAccountId {string}
- qs {object}
  - page {number} Page number. Starts from 0.
  - page_size {number} Page size. Default to 20.
  - application_status {string} Status filter. "pending", "approved" or "declined".

.notifications(params, callback)

Get account notifications

params {object}
- accountId {string}
- subAccountId {string}
- qs {object}
  - page {number} Page number. Starts from 0.
  - page_size {number} Page size. Default to 20.
  - start_time {number} List from this time. Unix timestamp.

.avatar(params, callback)

Get account avatar metadata

parameters:

params {object}
- accountId {string}
- subAccountId {string}

.avatarImg(params, callback)

Get account avatar raw image

parameters:

params {object}
- accountId {string}
- subAccountId {string}

.addressMetadata(address, callback)

Get address metadata

parameters:

address {string}

.joinedGroups(params, callback)

parameters:

params {object}
- accountId {string}
- subAccountId {string}
- qs {object}
  - page {number} Page number. Starts from 0.
  - page_size {number} Page size. Default to 20.

Token

.tokens(params, callback)

Get account tokens data

parameters:

params {object}
- accountId {string}

.incentives(params, callback)

Get incentives list

parameters:

params {object}
- accountId {string}
- qs {object}
  - start_date {number} Query start date. Unix timestamp.
  - end_date {number} Query end date. Unix timestamp.
  - page {number} Page number. Starts from 0.
  - page_size {number} Page size. Default to 20.

.incentiveStats(params, callback)

Get incentives statistics list

parameters:

params {object}
- accountId {string}
- qs {object}
  - start_date {number} Query start date. Unix timestamp.
  - end_date {number} Query end date. Unix timestamp.
  - page {number} Page number. Starts from 0.
  - page_size {number} Page size. Default to 20.

.incentiveWithdrawals(params, callback)

Get incentives withdrawal list

parameters:

params {object}
- accountId {string}
- qs {object}
  - start_date {number} Query start date. Unix timestamp.
  - end_date {number} Query end date. Unix timestamp.
  - page {number} Page number. Starts from 0.
  - page_size {number} Page size. Default to 20.
  - status {string} Status filter. "pending" or "done".

.createIncentiveWithdrawal(accountId, params)

Withdraw incentives

parameters:

accountId {string}
params {object} the object detail can be find in this page

.preLock(params, callback)

Get token pre-lock list

parameters:

params {object}
- accountId {string}
- qs {object}
  - start_date {number} Query start date. Unix timestamp.
  - end_date {number} Query end date. Unix timestamp.
  - page {number} Page number. Starts from 0.
  - page_size {number} Page size. Default to 20.
  - type {string} Type filter. "lock" or "unlock".

.createPreLock(accountId, params)

Pre-lock tokens

parameters:

accountId {string}
params {object} the object detail can be find in this page

.unPreLock(accountId, params)

Unlock pre-locked tokens

parameters:

accountId {string}
params {object} the object detail can be find in this page

.locks(params, callback)

Get token lock list

parameters:

params {object}
- accountId {string}
- qs {object}
  - start_date {number} Query start date. Unix timestamp.
  - end_date {number} Query end date. Unix timestamp.
  - page {number} Page number. Starts from 0.
  - page_size {number} Page size. Default to 20.
  - type {string} Type filter. "content", "group_create", "group_join" or "report".

Content

.content(params, callback)

Get content metadata

parameters:

params {object}
- contentId {string}

.raw(params, callback)

Get raw content

parameters:

params {object}
- contentId {string}

.create(params)

Post content

parameters:

params {object} the object detail can be find in this page

.update(contentId, params)

Update content

parameters:

contentId {string}
params {object} the object detail can be find in this page

.upgradeDTCPLinks(htmlContent, callback)

Upgrade DTCP links before posting

htmlContent {string}

Content Interaction

.shares(params, callback)

Get share metadata

params {object}
- shareId {string}
- qs {object}
  - account_id {string}

.groupShares(params, callback)

Get the shares of a group share

params {object}
- shareId {string}
- qs {object}
  - page {number}
  - page_size {number}
  - account_id {string}

.reports(params, callback)

Get share reports

params {object}
- shareId {string}
- qs {object}
  - page {number}
  - page_size {number}
  - report_status {"pending"|"approved"|"declined"}

.createReport(shareId, params)

Report share

shareId {string}
params {object} the object detail can be find in this page

.likes(params, callback)

Get the likes of a group share

params {object}
- shareId {string}
- qs {object}
  - page {number}
  - page_size {number}
  - account_id {string}

.createLike(shareId, params)

Like a group share

shareId {string}
params {object} the object detail can be find in this page

.cancelLike(shareId, likeId, params)

Cancel the like of a group share

shareId {string}
likeId {string}
params {object} the object detail can be find in this page

.comments(params, callback)

Get the comments of a group share

params {object}
- shareId {string}
- qs {object}
  - page {number}
  - page_size {number}
  - account_id {string}

.replys(params, callback)

Get replying comments of a comment

params {object}
- commentId {string}

.createComment(shareId, params)

The way comment content is processed is the same as post content API.

shareId {string}
params {object} the object detail can be find in this page

.updateComment(shareId, commentId, params)

Update the comment of a group share

shareId {string}
commentId {string}
params {object} the object detail can be find in this page

.cancelComment(shareId, commentId, params)

Delete the comment of a group share

shareId {string}
commentId {string}
params {object} the object detail can be find in this page

Group

.group(params, callback)

Get group metadata

params {object}
- groupId {string}
- qs object
  - account_id {string}

.create(params)

Create group

params {object} the object detail can be find in this page

.create(groupId, params)

Update group

groupId {string}
params {object} the object detail can be find in this page

.dismiss(groupId, params)

Update group

groupId {string}
params {object} the object detail can be find in this page

.members(params, callback)

Get group members

params {object}
- groupId {string}
- qs object
  - page {number}
  - page_size {number}
  - application_status {"pending"|"approved"|"declined"}

.join(groupId, params)

Join group

groupId {string}
params {object} the object detail can be find in this page

.approveOrDecline(groupId, groupMemberId, params)

Approve or decline member application

groupId {string}
groupMemberId {string}
params {object} the object detail can be find in this page

.quit(groupId, groupMemberId, params)

Quit group or kick member out

groupId {string}
groupMemberId {string}
params {object} the object detail can be find in this page

.whitelist(params, callback)

Get group member whitelist

params {object}
- groupId {string}
- qs object
  - page {number}
  - page_size {number}
  - application_status {"pending"|"approved"|"declined"}

.createWhitelist(groupId, params)

Add group member whitelist

groupId {string}
params {object} the object detail can be find in this page

.approveOrDeclineWhitelist(groupId, whitelistId, params)

Approve or decline group member whitelist

groupId {string}
whitelistId {string}
params {object} the object detail can be find in this page

.quitWhitelist(groupId, whitelistId, params)

Quit group member whitelist

groupId {string}
whitelistId {string}
params {object} the object detail can be find in this page

.shares(params, callback)

Get group shares

params {object}
- groupId {string}
- qs object
  - page {number}
  - page_size {number}
  - application_status {"pending"|"approved"|"declined"}

.createShare(groupId, params)

Share to a group

groupId {string}
params {object} the object detail can be find in this page

.approveOrDeclineShare(shareId, params)

Approve or decline share application

shareId {string}
params {object} the object detail can be find in this page

.cancelShare(shareId, params)

Delete group share

shareId {string}
params {object} the object detail can be find in this page

.avatar(params, callback)

Get group avatar metadata

params {object}
- groupId {string}

.avatarImg(params, callback)

Get group avatar raw image

params {object}
- groupId {string}

Node

.nodes(params, callback)

Get node list

params object
- qs object
  - page number
  - page_size number

Query

.query(params, callback)

Query all

params object
- qs object
  - page number
  - page_size number
  - text string
  - type "all"|"share"|"account"|"group"
  - category string

System

.system(callback)

Get system parameters

Timeline

.timeline(params, callback)

params {object}
- accountId {string}

Known Errors

result_code	result_msg	description
0	success	Success
400	client error	Client error
401	invalid data	Invalid post data
402	parse input JSON format error	Invalid JSON string
403	client signature error	Signature verification failed
404	input parameter error	Invalid parameter
405	input parameter empty	Empty parameter
406	nonce less than lasted	Nonce is used before
500	server error	Server error