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

• Primas-nodejs-sdk
• Install
• Compatibility
• Prerequisite
• Summary
• Basic Usage
• Metadata Sign
• Create A Primas Instance
• Operations
  • Account
    • .metadata(params, callback)
    • .addressMetadata(address, callback)
    • .create(params)
    • .update(accountId, params)
    • .credits(params, callback)
    • .contents(params, callback)
    • .groups(params, callback)
    • .shares(params, callback)
    • .sharesInGroup(params, callback)
    • .likes(params, callback)
    • .comments(params, callback)
    • .groupApplications(params, callback)
    • .shareApplications(params, callback)
    • .reports(params, callback)
    • .notifications(params, callback)
    • .avatar(params, callback)
    • .avatarImg(params, callback)
    • .addressMetadata(address, callback)
    • .joinedGroups(params, callback)
  • Token
    • .tokens(params, callback)
    • .incentives(params, callback)
    • .incentiveStats(params, callback)
    • .incentiveWithdrawals(params, callback)
    • .createIncentiveWithdrawal(accountId, params)
    • .preLock(params, callback)
    • .createPreLock(accountId, params)
    • .unPreLock(accountId, params)
    • .locks(params, callback)
  • Content
    • .content(params, callback)
    • .raw(params, callback)
    • .create(params)
    • .update(contentId, params)
    • .upgradeDTCPLinks(htmlContent, callback)
  • Content Interaction
    • .shares(params, callback)
    • .groupShares(params, callback)
    • .reports(params, callback)
    • .createReport(shareId, params)
    • .likes(params, callback)
    • .createLike(shareId, params)
    • .cancelLike(shareId, likeId, params)
    • .comments(params, callback)
    • .replys(params, callback)
    • .createComment(shareId, params)
    • .updateComment(shareId, commentId, params)
    • .cancelComment(shareId, commentId, params)
  • Group
    • .group(params, callback)
    • .create(params)
    • .create(groupId, params)
    • .dismiss(groupId, params)
    • .members(params, callback)
    • .join(groupId, params)
    • .approveOrDecline(groupId, groupMemberId, params)
    • .quit(groupId, groupMemberId, params)
    • .whitelist(params, callback)
    • .createWhitelist(groupId, params)
    • .approveOrDeclineWhitelist(groupId, whitelistId, params)
    • .quitWhitelist(groupId, whitelistId, params)
    • .shares(params, callback)
    • .createShare(groupId, params)
    • .approveOrDeclineShare(shareId, params)
    • .cancelShare(shareId, params)
    • .avatar(params, callback)
    • .avatarImg(params, callback)
  • Node
    • .nodes(params, callback)
  • Query
    • .query(params, callback)
  • System
    • .system(callback)
  • Timeline
    • .timeline(params, callback)
• Known Errors

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|