@rarify/js-sdk NPM

Rarify JavaScript SDK

version (scoped package) types checks last commit

The Rarify JavaScript SDK is a JavaScript library for the Rarify API. It provides reusable commands that make it easier to communicate with the API from client-side and server-side JavaScript applications.

For more information about the Rarify API, see the Rarify API reference at https://docs.rarify.tech/.

For full documentation about this SDK, see https://rarifytech.github.io/js-sdk/.

Installing the SDK

To install the SDK into a Web or Node.JS application, use npm or yarn to install the NPM package @rarify/js-sdk:

yarn add @rarify/js-sdk

To install the SDK in browser-side JavaScript via CDN, use this unpkg link, replacing [version] with the version that you want to use:

<script type="text/javascript" src="https://unpkg.com/@rarify/js-sdk@[version]/lib/rarify.js-sdk.min.js"></script>

<script type="text/javascript" src="https://unpkg.com/@rarify/js-sdk"></script>

To verify that the SDK is available in browser-side JavaScript, look for a message in the console that says "Rarify JS SDK was added to the window object."

Getting started

To start using the SDK, you must import the NPM package, create an instance of the SDK client, and give the client your API token.

There are two basic ways to import and use the SDK: you can import the entire package or reduce your application size by importing only specific groups of methods. Depending on the way you use, the methods that you can call and their responses are different, so be sure to know which way you're using.

Importing the entire package

To import the entire package in Node.JS, create an instance of the RarifyClient object, as in this example:

const { RarifyClient } = require('@rarify/js-sdk');

const AUTH_TOKEN = 'd6ef1960-6f6f-42ac-8ac1-d530652ca416';
const client = new RarifyClient(AUTH_TOKEN);

To import the entire package in browser-side JavaScript, create an instance of the RarifyClient object from the window.rarifySdk object, as in this example:

<script type="text/javascript" src="https://unpkg.com/@rarify/js-sdk"></script>

<script type="text/javascript">
  const AUTH_TOKEN = 'd6ef1960-6f6f-42ac-8ac1-d530652ca416';
  const client = new window.rarifySdk.RarifyClient(AUTH_TOKEN);
</script>

Or in a web application, you can import the RarifyClient object like this:

import { RarifyClient } from '@rarify/js-sdk';

const AUTH_TOKEN = 'd6ef1960-6f6f-42ac-8ac1-d530652ca416';
const client = new RarifyClient(AUTH_TOKEN);

Now you can use the methods on the instance of the RarifyClient object to call the Rarify API, as in this example:

const contract = await client.createContract(options);

const token = await client.getTokenERC1155MetadataById(contractId, tokenExternalId);

For reference information about the RarifyClient object and its methods, see RarifyClient in the SDK reference.

Importing only specific method groups

To reduce the size of your application and support tree-shaking, you can import only the groups of methods that you need, such as methods related to contracts or methods related to NFTs. Each group of methods is in a caller object. For example, this Node.JS code creates instances of the ContractCaller and TokenCaller objects in Node.JS, which provide methods for working with contracts and tokens:

const {
  JsonApiClient,
  ContractCaller,
  TokenCaller,
} = require('@rarify/js-sdk');

const apiCaller = new JsonApiClient({ baseUrl: 'https://api.rarify.tech/core' });
const AUTH_TOKEN = 'd6ef1960-6f6f-42ac-8ac1-d530652ca416';
apiCaller.setAuthToken(AUTH_TOKEN);

const contractCaller = new ContractCaller(apiCaller);
const tokenCaller = new TokenCaller(apiCaller);

This code creates instances of the ContractCaller and TokenCaller objects in browser-side JavaScript:

<script type="text/javascript" src="https://unpkg.com/@rarify/js-sdk"></script>

<script type="text/javascript">
  const apiCaller = new window.rarifySdk.JsonApiClient({ baseUrl: 'https://api.rarify.tech/core' });
  const AUTH_TOKEN = 'd6ef1960-6f6f-42ac-8ac1-d530652ca416';
  apiCaller.setAuthToken(AUTH_TOKEN);

  const contractCaller = new window.rarifySdk.ContractCaller(apiCaller);
  const tokenCaller = new window.rarifySdk.TokenCaller(apiCaller);
</script>

Or in a web application, you can import the objects like this:

import {
  JsonApiClient,
  ContractCaller,
  TokenCaller,
} from '@rarify/js-sdk';

const apiCaller = new JsonApiClient({ baseUrl: 'https://api.rarify.tech/core' });
const AUTH_TOKEN = 'd6ef1960-6f6f-42ac-8ac1-d530652ca416';
apiCaller.setAuthToken(AUTH_TOKEN);

const contractCaller = new ContractCaller(apiCaller);
const tokenCaller = new TokenCaller(apiCaller);

Now you can use the methods on the instances of the ContractCaller and TokenCaller objects, as in this example:

const { data: contract } = await contractCaller.createContract(options);

const { data: token } = await tokenCaller.createToken(contractId, metadataId);

For reference information about the JsonApiClient object and the caller objects, see the SDK reference.

Using the SDK

To make sure that the SDK is working, try a straightforward command, such as listing the available networks. These commands call the GET /core/networks endpoint, but the method and response is different depending on how you imported the package.

If you imported the entire package, call the RarifyClient.getAllNetworks() method. This method returns a Promise that resolves to a list of Network JavaScript objects.

const { RarifyClient } = require('@rarify/js-sdk');

const AUTH_TOKEN = 'd6ef1960-6f6f-42ac-8ac1-d530652ca416';
const client = new RarifyClient(AUTH_TOKEN);

async function getNetworks() {
  const networkList = await client.getAllNetworks()
  console.log(networkList);
}

getNetworks();

If you are using an instance of the NetworkCaller object, call the NetworkCaller.getNetworks() method. Like most methods on the caller objects, this method returns a Promise that resolves to a JsonApiResponse. The information about the networks is in the data field.

const apiCaller = new JsonApiClient({ baseUrl: 'https://api.rarify.tech/core' });

apiCaller.setAuthToken('d6ef1960-6f6f-42ac-8ac1-d530652ca416');

const networkCaller = new NetworkCaller(apiCaller);

async function getNetworks() {
  const { data: networks } = await networkCaller.getNetworks();
  console.log(networks);
}

getNetworks();

Creating tokens

As with using the Rarify API directly, creating tokens with the SDK has these major steps:

Step 1: Create a contract

To create a contract, use the client.createContract() or contractCaller.createContract() method. These methods call the POST /core/contracts endpoint. Just like the endpoint, this method accepts the type of contract to create and the network to create it on. If you omit the network, the SDK uses Polygon as the default network.

For more information about creating a contract with Rarify, see Creating tokens in the Rarify API reference.

This example uses the RarifyClient object:

const { RarifyClient } = require('@rarify/js-sdk');

const AUTH_TOKEN = 'd6ef1960-6f6f-42ac-8ac1-d530652ca416';
const client = new RarifyClient(AUTH_TOKEN);

async function createContract() {

  // To get an image file for the contract in Node.JS, use fs.createReadStream().
  // To get an image file on a web page, you can use a File instance from a <select> element's change event.
  const contract = await client.createContract({
    name: 'My contract from SDK',
    image: file.value as File,
    networkId: 'polygon',
    erc1155: {
      metadata: {
        royalties_fee_basic_points: 250,
        royalties_receiver: '0x1234567890',
        description: 'My example contract that I use to create ERC1155 NFTs',
        external_url: 'https://rarify.tech/',
        image_url: 'https://s3.eu-west-1.amazonaws.com/rarify.tech/main-splash.png',
        name: 'My example ERC1155 NFT collection',
      },
    },
  });
  console.log(contract);
}

createContract();

This example uses the JsonApiCaller and ContractCaller objects:

const {
  JsonApiClient,
  ContractCaller,
} = require('@rarify/js-sdk');

const apiCaller = new JsonApiClient({ baseUrl: 'https://api.rarify.tech/core' });

apiCaller.setAuthToken('d6ef1960-6f6f-42ac-8ac1-d530652ca416');

const contractCaller = new ContractCaller(apiCaller);

const myIdentity = '233f2794-a8d7-4689-b84b-15a293eb6d1d';

async function createContract() {

  return contractCaller.createContract({
    name: 'My contract from SDK',
    erc1155: {
      metadata: {
        royalties_fee_basic_points: 250,
        royalties_receiver: "0x1234567890",
        description: "My example contract that I use to create ERC1155 NFTs",
        external_url: "https://rarify.tech/",
        image_url: "https://s3.eu-west-1.amazonaws.com/rarify.tech/main-splash.png",
        name: "My example ERC1155 NFT collection",
      },
    },
    networkId: 'polygon',
    ownerId: myIdentity,
  });
}

createContract();

The response includes the ID of the transaction that the Rarify API is using to create the contract on the network. Creating a contract on a network is an asynchronous action, so you can use the transaction ID to check the progress of the action or to accept a callback when the contract is created. For more information about these asynchronous events and setting up callbacks for them, see Using callbacks in the API reference.

Step 2: Create a token design

Rarify allows you to set up tokens and their metadata payload on its API before you mint tokens on the target network. This way, you can plan and test tokens before you incur costs.

The commands in the following examples call the the PUT /core/metadata and POST /core/tokens endpoints.

To create a token design with the RarifyClient object, you pass the metadata information and other token information to the RarifyClient.createToken() method. There is no separate method to create metadata when you use this object.

const { RarifyClient } = require('@rarify/js-sdk');

const AUTH_TOKEN = 'd6ef1960-6f6f-42ac-8ac1-d530652ca416';
const client = new RarifyClient(AUTH_TOKEN);

async function createToken() {
  const contractId = '7863a087-43fe-46a6-bac1-3a652121f2a8';

  // To get an image file for the contract in Node.JS, use fs.createReadStream().
  // To get an image file on a web page, you can use a File instance from a <select> element.
  const token = await client.createToken({
    name: 'My token from SDK',
    description: 'Description for my token'
    image: file.value as File,
    contractId: contractId,
    externalUrl: "https://rarify.tech/",
  });
  console.log(token);
}

createToken();

To create a token design with the JsonApiClient object, first create a metadata object and then assign that metadata to the token design, as in this example:

const {
  JsonApiClient,
  FileCaller,
  MetadataCaller,
  TokenCaller,
} = require('@rarify/js-sdk');

const apiCaller = new JsonApiClient({ baseUrl: 'https://api.rarify.tech/core' });

apiCaller.setAuthToken('d6ef1960-6f6f-42ac-8ac1-d530652ca416');

const fileCaller = new FileCaller(apiCaller);
const metadataCaller = new MetadataCaller(apiCaller);
const tokenCaller = new TokenCaller(apiCaller);

const myIdentity = '233f2794-a8d7-4689-b84b-15a293eb6d1d';
const contractId = '2d344525-2b11-4372-8b00-8ddeeb88fdb6';

async function createToken() {
  // Upload image
  // To get an image file for the contract in Node.JS, use fs.createReadStream().
  // To get an image file on a web page, you can use a File instance from a <select> element.
  const { data: image } = await fileCaller.uploadFile(
    file,
    myIdentity,
  );

  const { data: metadata } = await metadataCaller.setMetadata({
    name: 'My token',
    description: 'A token design I created with the SDK',
    imageUrl: image.url,
    externalUrl: 'https://rarify.tech/',
    networkId: 'polygon',
    ownerId: myIdentity,
  });

  const { data: token } = await tokenCaller.createToken(
    contractId,
    metadata.id,
  );

  console.log(token);
}

createToken();

Step 3: Mint a token

Now that you have a token design with metadata, you can mint instances of the token. Minting the token creates one or more specific instances of the token on the target network and incurs network costs, so be sure that the design is correct and that you specify the correct recipient and other information. The following examples call the POST /core/transfers endpoint.

To mint tokens with the RarifyClient object, pass the token design ID, the number of tokens, the receiver's wallet address, and whether you are minting tokens or transferring existing tokens to the RarifyClient.transferTokens() method, as in this example:

const { RarifyClient } = require('@rarify/js-sdk');

const AUTH_TOKEN = 'd6ef1960-6f6f-42ac-8ac1-d530652ca416';
const client = new RarifyClient(AUTH_TOKEN);

async function mintTokens() {

  const transfer = await client.transferTokens({
    tokenId: '6743529b-50c5-4acf-86b7-25c260f99427',
    amount: 1,
    isMinting: true,
    receiver: '0x12345',
  });

  console.log(transfer);
}

mintTokens();

To mint tokens with the JsonApiClient object, pass the token design ID, number of tokens, and the receiver's wallet address to the TransferCaller.transferTokens() method, as in this example:

const {
  JsonApiClient,
  TransferCaller,
} = require('@rarify/js-sdk');

const apiCaller = new JsonApiClient({ baseUrl: 'https://api.rarify.tech/core' });

apiCaller.setAuthToken('d6ef1960-6f6f-42ac-8ac1-d530652ca416');

const transferCaller = new TransferCaller(apiCaller);

async function mintTokens() {

  const { data: transfer } = await transferCaller.transferTokens({
    tokenId: '6743529b-50c5-4acf-86b7-25c260f99427',
    amount: 1,
    isMinting: true,
    receiver: '0x12345',
  });

  console.log(transfer);
}

mintTokens();

Minting tokens on a network is an asynchronous action, so you can use the transaction ID to check the progress of the action or to accept a callback when the transaction is complete. Now that you have minted the token the target network, you can use it like any other token on the network or use the Rarify API to transfer it between accounts. The request is similar, but instead of setting is_minting to true, set it to false and specify the new owner of the token.

Step 4: Get the status of a transaction

To get the status of transactions, such as the transaction that is minting a token, use the RarifyClient.getTransactions() or transactionCaller.getTransactions() methods. These commands call the GET /core/transactions endpoint.

This example uses the RarifyClient.getTransactions() method:

const { RarifyClient } = require('@rarify/js-sdk');

const AUTH_TOKEN = 'd6ef1960-6f6f-42ac-8ac1-d530652ca416';
const client = new RarifyClient(AUTH_TOKEN);

async function getTransactions() {
  const { data: transactions } = await client.getTransactions({
    page: {
      number: 0,
      limit: 20,
      order: 'desc',
    },
  });
  console.log(transactions);
}

getTransfer();

This example uses the TransactionCaller.getTransactions() method:

const {
  JsonApiClient,
  TransactionCaller,
} = require('@rarify/js-sdk');

const apiCaller = new JsonApiClient({ baseUrl: 'https://api.rarify.tech/core' });

apiCaller.setToken('d6ef1960-6f6f-42ac-8ac1-d530652ca416');

const transactionCaller = new TransactionCaller(apiCaller);

const myIdentity = '233f2794-a8d7-4689-b84b-15a293eb6d1d';

async function getTransactions() {
  const { data: transactions } = await transactionCaller.getTransactions({
    'filter[owner]': myIdentity,
    'page[limit]': '10',
    'page[order]': 'desc',
  }, ['transfer', 'contract']);
  return transactions;
}

getTransactions();

The response includes the state and ID of the transaction. If the transaction succeeded, the state field is set to applied and the hash field provides the hex ID that you can use to look up the new token on the network.

Development

These instructions are for developing and building the SDK locally.

For the development environment we use:

Eslint plus Prettier for the linting and formatting code.
Jest for unit tests.

Build bundles

@rarify/js-sdk compiles into the es-modules and also there is distributive for "in-script-tag" usage that compiles into the ./lib/rarify.js-sdk.min.js output file, which will accessible in the Window object with property name .rarifySdk

Before developing or building library distributive you'll need to install node_modules, use npm install or yarn install.

To build library distributive you can execute yarn build that will compile the type definitions, ES-modules, CommonJS bundles and browser bundle, or you can with one command:

Build type definitions with TypeScript compiler:

yarn build:types

This command emits all type definitions from library without JavaScript compiling, also we use tsc-alias tool to replace all alias-ed type definitions paths to the relative one.

Compile and minify library into the ES, CJS modules and browser compatible bundle: