@alphawallet/token-negotiator v0.1.4
token-negotiator
The token-negotiator is an NPM package designed for use with TokenScript.
TokenScript is a framework which improves functionality, security and usability of blockchain token. It creates a layer between a blockchain and user devices, adding information, rules and functionalites both onchain and offchain.
For more information please visit: https://tokenscript.org/.
Examples
https://tokenscript.github.io/token-negotiator-examples/
Documentation
Usage
npm i @alphawallet/token-negotiator
import { Negotiator } from '@alphawallet/token-negotiator';
Negotiator
Creates a new instance of the Negotiator module.
/**
*
* @param {Object} filter optional filter rules
* @param {Object} options api options (required options shown below)
* @param {String} tokenName name (required)
*/
const negotiator = new window.Negotiator({
filter: { 'devconId': 6 },
tokenName: "devcon-ticket",
options: { userPermissionRequired: true }
});
Resolves the tokens with filter applied.
/**
*
* @returns {object} token data { success: true/false, tokens: [...{}] }
*/
const negotiatedTokens = await negotiator.negotiate();
Authenticate ownership of Token.
/**
* @param {URL} unEndPoint end point must return { un: number, expiry: date }
* @param {object} unsignedToken selected un-signed token/ticket
* @returns {object} { status (true/false), useToken (object), useEthKey (object)
* - useTicket and ethKey can be used to verify a ticket is valid.
* - status indicates if the function was successful.
*/
const { status, useToken, useEthKey } = await negotiator.authenticate({ unEndPoint, unsignedToken });
Filters
When loading a page you may wish to only show a select set of tokens.
For example: with the following key/values devconId, ticketId, ticketClass
you may wish to only show devconId
when the value is 6
and of ticketClasses
of A
. Below is an example of how this can be applied.
const negotiator = new window.Negotiator({
filter: { devconId: 6, ticketClass: "A" },
tokenName: "devcon-ticket",
options: {}
});
Negotiator Options
userPermissionRequired
- Default is false. When true, the Token Negotiator will not allow negotiate()
to be used until access is given. This feature can be thought of in a similar way to how cookies are managed with end user permissions.
Example Use below:
// token list
let tokens = [];
// initial config object
const negotiator = new window.Negotiator({
filter: { 'devconId': 6 },
tokenName: "devcon-ticket",
options: { userPermissionRequired: true }
});
// An example click event where the User clicks 'Yes' or 'No' to allow access.
const userPermissionClickEvent = (bool) => {
// set permission inside negotiator state
negotiator.setUserPermission(bool);
// if the user has selected to give access
if(negotiator.getUserPermission() === true){
// get the tokens and utilise them in the web application
negotiator.negotiate().then(result => {
tokens = result.tokens;
});
}
}
User consent to connect the website to the token, this is only required when 'userPermissionRequired' is set as true.
/**
* @param {Boolean} boolean
*/
negotiator.setUserPermission(boolean);
The Negotiator will hold state of the permission, which can be accessed at any time.
/**
* @returns {Boolean} boolean
*/
negotiator.getUserPermission();