@rarify/js-sdk

@rarify/js-sdk

JS SDK Type reference: https://rarifytech.gitlab.io/js-sdk

Rarify API Documentation: https://docs.rarify.tech/

Table of Contents

• What is this?
• Install
• Usage
• Development
  • Build bundles
  • Build documentation
• Changelog

What is this?

Rarify JS SDK is a client-side Javascript library for the Rarify platform, that provides reusable interfaces to make it easier to communicate with the backend.

How do I use it?

Install

Install via npm:

yarn add @rarify/js-sdk

Install via unpkg CDN:

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

Usage

You can make api.ts file in your project that will initialize and exports api callers which represents HTTP requests to the backend:

import {
  JsonApiClient,
  NetworkCaller,
  ContractCaller,
  FileCaller,
  MetadataCaller,
  TokenCaller,
  TransferCaller
} from '@rarify/js-sdk'

// Initiate JsonApiCaller:
export const apiCaller = new JsonApiClient({ baseUrl: 'https://api.rarify.tech' })

// Set authorization token:
apiCaller.setToken('70fc6930-0f9c-42d4-afcc-ea756331e309')

// Initiate endpoint-callers with JsonApiCaller:
export const networkCaller = new NetworkCaller(apiCaller)
export const contractCaller = new ContractCaller(apiCaller)
export const fileCaller = new FileCaller(apiCaller)
export const metadataCaller = new MetadataCaller(apiCaller)
export const tokenCaller = new TokenCaller(apiCaller)
export const transferCaller = new TransferCaller(apiCaller)

After that you need to import all required api callers and types into file where you will implement token creation logic:

// Import types:
import { FileLike, Uuid, Token, RarifyERC721, RarifyERC1155 } from '@rarify/js-sdk'

// Import callers:
import {
  apiCaller,
  networkCaller,
  contractCaller,
  fileCaller,
  metadataCaller,
  tokenCaller,
  transferCaller,
} from './api.ts'

Next step is get network list:

const networks = await networkCaller.getNetworks()

Find network that supports contract creation:

const contractNetworkId = networks.find(item => item.tokens_minting)

Create contract with founded network ID:

const contract = await contractCaller.createContract({
  name: 'NewContract',
  erc721: { /* ERC721 contract data */ },
  erc1155: { /* ERC1155 contract data */ },
  networkId: contractNetworkId,
  ownerId: identityId /* Your account identity ID */
})

Implement creating token function:

const createToken = async (params: {
  name: string,
  description: string,
  file: FileLike,
  identityId: Uuid,
  contractId: Uuid,
}): Promise<Token> => {
  // Get network that supports metadata storage to store token metadata
  const metadataStorageNetworkId = networks.find(item => item.metadata_storage)

  // Upload image
  const image = await fileCaller.uploadFile(
    params.file,
    params.identityId
  )

  // Set token metadata:
  const metadata = await metadataCaller.setMetadata({
    name: params.name,
    description: params.description,
    imageUrl: image.url,
    networkId: metadataStorageNetworkId,
    ownerId: params.identityId,
  })

  // Finally, create and return created token:
  return tokenCaller.createToken(
    params.contractId,
    metadata.id
  )
}

Mint token to some address:

const token = await createToken(/* Create token parameters */)

const transfer = await transferCaller.transferTokens({
  tokenId: token.id,
  amount: 1,
  isMinting: true,
  receiver: '0x12345...' // Wallet address
})

After these steps there will have all logic you need to create and mint token on Rarify platform.

Development

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 distributives you can execute yarn build that will compile the type definitions, es-module bundle and browser bundle, or you can do each step manually:

Remove all compiled distributions from ./lib directory:

yarn clean

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-modules with Babel.js:

yarn build:js

It will remove all comments, whitespaces, transpile and minify output JavaScript code.

Build browser compatible bundle with esbuild:

yarn build:browser

There are some npm scripts that will help during development:

Run tests:

yarn test

Serve tests during development or fixing:

yarn test:watch

Check types with TypeScript compiler:

yarn type-check

Lint source code:

yarn lint

Check out CHANGELOG.md and package.json files for release version changes:

yarn rsc %release-version%

Example: yarn rsc 1.0.0-rc.0

Built and tested on node v14.18.1.

Build documentation

We use Typedoc tool to compile docs from the source code, you can build it for the local usage like this, output will be located in ./docs:

yarn docs

Changelog

All notable changes to this project will be documented in this file. This project adheres to Semantic Versioning.