Shelf.Network JavaScript SDK

The Shelf.Network JavaScript SDK facilitates client integration with the Shelf.Network auction platform.

Table of content

Javascript SDK
Development Guide
Troubleshooting

JavaScript SDK

Installation

npm install -S @shelf.network/js-sdk

Webpack

If you use webpack as your build system, you'll need to exclude the optional native module ed25519

  plugins: [
    new webpack.IgnorePlugin(/ed25519/)
  ]

You can also check out package's webpack config.

Shelf.Network SDK

To get started, create a Shelf.Network SDK instance:

import { ShelfNetwork } from '@shelf.network/js-sdk'

const sdk = await ShelfNetwork.create({
  gatewayUrl: 'https://api.staging.shelf.network'
})

You can configure different environment setting such as proxy configuration via options.

Response Format

All HTTP responses share the following format:

{
  httpStatus: 200,

  // Flattened and camel-cased response data
  data: [
    {
      resourceType: 'deposits',
      id: '209529',
      accountId: 'GDWF6Q7MAFWGJG2NFP75RESDKL33QUVPREP4MGSZ3BGS5BYWOHU3GJ2A',
      amount: '4267.00',
      currency: 'GEL',
      state: 2,
      stateStr: 'paid'
    }
  ],

  // Response headers
  headers: {...},

  // Parsed links and relations
  fetchNext: () => {...},
  fetchPrev: () => {...},
  fetchAccount: () => {...}
}

The links and relations that are returned with the responses are converted into functions you can call on the returned object. For example you can use them for simple pagination through collections:

const page = await sdk.horizon.balances.getPage()
console.log('Page', page.data)

const prevPage = await page.fetchPrev()
console.log('Previous page', prevPage.data)

Errors

Common errors

Wrappers for error responses

All the error responses subclass ServerErrorBase and share the following format:

{
  httpStatus: 403,
  // Human readable title
  title: 'Forbidden',
  // Detailed explanation
  detail: 'Additional factor required.',
  // Additional relevant data
  meta: {
    factorId: 275,
    factorType: 'password',
    ...
  },
  // Raw unparsed error
  originalError: {...},
  // Retry request. Handy for 2FA handling
  retryRequest: () => {...}
}

Interceptors

SDK allows you to use request and response interceptors:

sdk.useRequestInterceptors(
  request => {
    // Track user's actions, transform request data, etc
  },
  err => {
    // Log, handle errors, retry requests, etc
  }
)

sdk.useResponseInterceptor(
  config => {
    // Parse and transform response data, show notifications, etc
  },
  err => {
    // Track errors, try to retry requests, show 2FA prompts, etc
  }
)

Authentication

Each request is authenticated to each service via JWT. A token is represented by the base64 string stored in Authorization header with syntax Bearer {token}.

A client passes his credentials upon registration. Later this credentials will be used to retrieve temporary JWTs.

Retrieve and use the token to authenticate requests

const token = await sdk.auth.getToken('my@email.com', 'MyPassw0rd', platformId)
sdk.useToken(token)

Refresh a token

const newToken = await sdk.auth.refreshToken()
sdk.useToken(newToken)

Change password

await sdk.auth.changePassword('oldPassword', 'newPassword')

Request password recovery

await sdk.auth.requestRecovery('my@email.com')

Confirm recovery

// accountId, token are parsed from the recovery link
await sdk.auth.confirmRecovery(accountId, token, 'newPassword')

Services and Resource Groups

Each backend service has an associated object attached to an SDK instance that inherits ServerBase class. It contains methods that encapsulate endpoint calls and may also have some associated resource groups.

List of services and associated resource groups:

Development Guide

Build

Build for node.js:

npm run build

Coding Style

SDK follows JavaScript Standard Style.

All public classes and functions must have JSDoc annotations.

Run linter to check for style violations:

npm run lint

Testing

Node.js tests:

npm test

Test coverage:

npm run coverage

Generating Docs

npm run docs