Stelace Javascript SDK

Stelace Javascript SDK makes it easy to use Stelace API in your client or server-side JavaScript applications.

What is Stelace?

Stelace provides search, inventory and user management infrastructure for Web platforms, ranging from search-intensive marketplaces to online community apps. Stelace offers powerful backend and APIs including advanced search, automation, and content delivery, to let you focus on what makes your platform unique.

Core Features

Full Stelace API endpoints coverage
API key and Auth Tokens handling
ES6 modules / bundler support

Supported browsers and Node.js versions

Chrome
Firefox
Edge
Safari
IE11 (except when using pre-packaged evergreen version)
Node.js (>=10.18)

Other browsers with similar feature set should also work.

Installation

npm install stelace
# Or
yarn stelace

This package needs to be used with secret or publishable api keys you can find in Stelace Dashboard.

Node

const { createInstance } = require('stelace')
const stelace = createInstance({ apiKey: 'seck_test_...' })

const asset = await stelace.assets.create({
  name: 'Car'
})

With callback

const Stelace = require('stelace')
const stelace = Stelace.createInstance({ apiKey: 'seck_test_...' })

stelace.assets.create({
  name: 'Car'
}, function (err, asset) {
  err // null if no error occurred
  asset // the created asset object
})

Warning: secret apiKey seck_... must only be used in secure environments as it grants all endpoint permissions.

Browser

For browser you can either install (with npm/yarn) or add a <script> tag in your HTML.

ES module

Installing the SDK is the recommended way:

tree-shaking can reduce Stelace SDK size by 70% with shared dependencies (mostly axios and core-js polyfills).
no surprise due to potential jsDelivr/unpkg CDN failure.

You just have to use ES modules with your favorite bundler like Webpack:

import { createInstance } from 'stelace'
const stelace = createInstance({ apiKey: 'pubk_test_...' })
//…

Note: please use publishable apiKey pubk_... in browser environment.

Script tag

For convenience you may want to load one of the UMD files we built for you instead:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/stelace.browser.min.js"></script>

You can then use stelace global variable.

We offer a smaller build for modern browsers (excluding IE11 and Opera Mini in particular):

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/stelace.evergreen.min.js"></script>

Unminified and map files are also available.

Usage

Authentication

A publishable api key identifies your platform and enables all publicly accessible endpoints.

You’ll often need to call endpoints as one of your authenticated platform users (typically from your front-end).

Publishable apiKey is also what you need here since each user has its own set of permissions depending on user roles: all user permissions are automatically added to public permissions.

const { createInstance } = require('stelace')
const stelace = createInstance({ apiKey: 'pubk_test_...' })

// Login as the user '[email protected]'
await stelace.auth.login({
  username: '[email protected]',
  password: 'secretPassword'
})

// Any actions performed will be associated to this user
await stelace.assets.create(...)

// Logout to destroy the current session
await stelace.auth.logout()

After successful login, the access and refresh tokens will be returned.

Stelace SDK handles the authentication for you and will automatically renew the access token when it's expired.

Custom authentication

Advanced options are available for custom authentication workflows.

Token store

By default, Stelace provides a default token store for the authentication tokens storage. Tokens are stored into localStorage in browser environment and into memory in Node.js.

If custom storage is needed, a token store can be provided at initialization:

const myCustomTokenStore = {...}
const stelace = createInstance({ apiKey: 'pubk_test_...', tokenStore: myCustomTokenStore })

or at run-time:

stelace.setTokenStore(myCustomTokenStore)

A token store must be an object implementing the following functions:

getTokens()
setTokens(tokens: Object)
removeTokens()

For convenience, we provide stelace.getTokenStore() if you need to perform some operation on tokens.

Refreshing tokens your way

In some case (e.g. external authentication), you may need a custom workflow to refresh tokens.

beforeRefreshToken function can also be provided at initialization:

const myBeforeRefreshToken = function (tokens, cb) {
  getNewTokens(tokens, function (err, newTokens) {
    cb(err, newTokens)
  })
}

const stelace = createInstance({ apiKey: 'pubk_test_...', beforeRefreshToken: myBeforeRefreshToken })

or at run-time:

stelace.setBeforeRefreshToken(myBeforeRefreshToken)

The function beforeRefreshToken can also be a promise:

const myBeforeRefreshToken = async function (tokens) {
  const newTokens = await getNewTokens(tokens)
  return newTokens
}

Note: Any token will be stored as is in token store.

Using Promises

Each method request returns a promise (or await as above) that you can use in place of callbacks:

// Create an asset type and create an asset with it
stelace.assetTypes.create({
  name: 'Renting',
  timeBased: true,
  infiniteStock: false
}).then(function (assetType) {
  return stelace.assets.create({
    name: 'Car',
    assetTypeId: assetType.id
  })
}).then(function (asset) {
  // Created asset
}).catch(function (err) {
  // Handle this error
})

Examining Responses

Some information about the response is provided in the lastResponse property as convenience:

asset.lastResponse.requestId
asset.lastResponse.statusCode

When pagination is available in list endpoints, you’ll directly get results array as response:

const assets = await stelace.assets.list()
console.log(Array.isArray(assets)) // true
console.log(assets.lastResponse.statusCode) // 200

// For API version 2019-05-20 (offset pagination)
console.log(assets.paginationMeta.page) // 1

// For higher API version (cursor pagination)
console.log(assets.paginationMeta.hasNextPage)

Here are the properties included in paginationMeta:

For API version 2019-05-20 (offset pagination):

assets.paginationMeta.nbResults
assets.paginationMeta.nbPages
assets.paginationMeta.page
assets.paginationMeta.nbResultsPerPage

For higher API version (cursor pagination):

assets.paginationMeta.startCursor
assets.paginationMeta.endCursor
assets.paginationMeta.hasPreviousPage
assets.paginationMeta.hasNextPage
assets.paginationMeta.nbResultsPerPage

Currently, the following list endpoints don't support pagination:

asset type
category
role
webhook
workflow

Options

Options are additional parameters that you can pass after the required arguments after any given method.

All methods can accept an optional options object containing one or more of the following:

stelaceVersion - use a specific Stelace API version for this request
stelaceUserId - perform the request as the specified user ID, needs specific permissions to do so
stelaceOrganizationId - perform the request as the specified organization ID, the user must belong to the specified organization; null value allowed to remove the global value set by stelace.setOrganizationId()

This options object can be included as the last argument for any method (or second to last when using callbacks):

// Only the category data object
stelace.categories.create({
  name: 'Sport'
})

// The category data object and the options object
stelace.categories.create({
  name: 'Sport'
}, {
  stelaceVersion: '2018-07-30'
})

Configuring Timeout

Request timeout in case of network failure is configurable (the default is 30 seconds):

stelace.setTimeout(10000); // in ms (10 seconds)

API version compatibility

The current version of SDK (0.14.0) is compatible with Stelace API up to version 2019-05-20.

Development

Run all tests:

yarn
yarn prepare # To install husky hooks
yarn test

Run tests in browser environments (Chrome and Firefox):

yarn test:browser-local

SDK documentation

Most of the methods follow the same schema concerning arguments:

Id: string - Object ID

queryParams: object - Query parameters in GET requests (usually for pagination)

data: object - Body of the request for POST/PATCH requests (usually for creation or update of an object)

options: object - Options parameters described above

callback: function - Callback function. Omit it when using promises

The optional arguments are within [brackets].

API keys

List API keys

stelace.apiKeys.list([queryParams], [options], [callback])

Read an API key

stelace.apiKeys.read(apiKeyId, [queryParams], [options], [callback])

Create an API key

stelace.apiKeys.create(data, [options], [callback])

Update an API key

stelace.apiKeys.update(apiKeyId, data, [options], [callback])

Remove an API key

stelace.apiKeys.remove(apiKeyId, [options], [callback])

Assets

List Assets

stelace.assets.list([queryParams], [options], [callback])

Read an Asset

stelace.assets.read(assetId, [queryParams], [options], [callback])

Create an Asset

stelace.assets.create(data, [options], [callback])

Update an Asset

stelace.assets.update(assetId, data, [options], [callback])

Remove an Asset

stelace.assets.remove(assetId, [options], [callback])

Asset types

List Asset types (no pagination)

stelace.assetTypes.list([queryParams], [options], [callback])

Read an Asset type

stelace.assetTypes.read(assetTypeId, [queryParams], [options], [callback])

Create an Asset type

stelace.assetTypes.create(data, [options], [callback])

Update an Asset type

stelace.assetTypes.update(assetTypeId, data, [options], [callback])

Remove an Asset type

stelace.assetTypes.remove(assetTypeId, [options], [callback])

Authentication

Login

stelace.auth.login(data, [options], [callback])

Get current session info

stelace.auth.info()

Returns an object with the following properties:

isAuthenticated: boolean
userId: string|null

Logout

stelace.auth.logout()

User session expiration

To detect when the user session has expired and handle it properly, you can listen to the following error event:

stelace.onError('userSessionExpired', function () {
  // In browser, you can notify users that they must reconnect
  // ...
})

If there are any authentication tokens, they will be automatically removed.

To stop listening to the event, you can unsubscribe by calling the returned function:

const unsubscribe = stelace.onError('userSessionExpired', function () { ... })
unsubscribe() // stops listening

Get tokens after SSO or social login

stelace.auth.getTokens(data, [options], [callback])

Check authentication information

stelace.auth.check(data, [options], [callback])

Forward methods (advanced usage)

Following methods are provided to hit custom endpoints with Stelace authentication headers. This is especially useful if you need to call external endpoints with custom logic, e.g. using serverless lambda functions.

url can be a relative path to Stelace REST API endpoints or an absolute external URL. Stelace API endpoint (relative) path is equivalent to using the equivalent SDK method, like:

stelace.users.create(data)
// same as
stelace.forward.post('/users', data)

forward.methods map to corresponding HTTP verbs.

GET verb

stelace.forward.get(url, [callback])

POST verb

stelace.forward.post(url, [data], [callback])

PUT verb

stelace.forward.put(url, [data], [callback])

PATCH verb

stelace.forward.patch(url, [data], [callback])

DELETE verb

stelace.forward.del(url, [callback])

OPTIONS verb

stelace.forward.options(url, [callback])

Availability

Get availabilities graph

stelace.availabilities.getGraph([queryParams], [options], [callback])

List availabilities

stelace.availabilities.list([queryParams], [options], [callback])

Create an availability

stelace.availabilities.create(data, [options], [callback])

Update an availability

stelace.availabilities.update(availabilityId, data, [options], [callback])

Remove an availability

stelace.availabilities.remove(availabilityId, [options], [callback])

Config

Read config

stelace.config.read([options], [callback])

Update config

stelace.config.update([data], [options], [callback])

Read private config

stelace.config.readPrivate([options], [callback])

Update private config

stelace.config.updatePrivate([data], [options], [callback])

Custom attributes

List custom attributes

stelace.customAttributes.list([queryParams], [options], [callback])

Read a custom attribute

stelace.customAttributes.read(customAttributeId, [queryParams], [options], [callback])

Create a custom attribute

stelace.customAttributes.create(data, [options], [callback])

Update a custom attribute

stelace.customAttributes.update(customAttributeId, data, [options], [callback])

Remove a custom attribute

stelace.customAttributes.remove(customAttributeId, [options], [callback])

Documents

Get documents’ stats

stelace.documents.getStats([queryParams], [options], [callback])

List documents

stelace.documents.list([queryParams], [options], [callback])

Read a document

stelace.documents.read(documentId, [queryParams], [options], [callback])

Create a document

stelace.documents.create(data, [options], [callback])

Update a document

stelace.documents.update(documentId, data, [options], [callback])

Remove a document

stelace.documents.remove(documentId, [options], [callback])

Entries

List entries

stelace.entries.list([queryParams], [options], [callback])

Read an entry

stelace.entries.read(entryId, [queryParams], [options], [callback])

Create an entry

stelace.entries.create(data, [options], [callback])

Update an entry

stelace.entries.update(entryId, data, [options], [callback])

Remove an entry

stelace.entries.remove(entryId, [options], [callback])

Events

Get events’ stats

stelace.events.getStats([queryParams], [options], [callback])

List events

stelace.events.list([queryParams], [options], [callback])

Read an event

stelace.events.read(eventId, [queryParams], [options], [callback])

Create an event

stelace.events.create(data, [options], [callback])

Messages

List messages

stelace.messages.list([queryParams], [options], [callback])

Read a message

stelace.messages.read(messageId, [queryParams], [options], [callback])

Create a message

stelace.messages.create(data, [options], [callback])

Update a message

stelace.messages.update(messageId, data, [options], [callback])

Remove a message

stelace.messages.remove(messageId, [options], [callback])

Orders

List orders

stelace.orders.list([queryParams], [options], [callback])

Read an order

stelace.orders.read(orderId, [queryParams], [options], [callback])

Preview an order

stelace.orders.preview(data, [options], [callback])

Create an order

stelace.orders.create(data, [options], [callback])

Update an order

stelace.orders.update(orderId, data, [options], [callback])

Order lines

Read an order line

stelace.orderLines.read(orderLineId, [queryParams], [options], [callback])

Create an order line

stelace.orderLines.create(data, [options], [callback])

Update an order line

stelace.orderLines.update(orderLineId, data, [options], [callback])

Order moves

Read an order move

stelace.orderMoves.read(orderMoveId, [queryParams], [options], [callback])

Create an order move

stelace.orderMoves.create(data, [options], [callback])

Update an order move

stelace.orderMoves.update(orderMoveId, data, [options], [callback])

Password

Change the password

stelace.password.change(data, [options], [callback])

Send a password reset request

stelace.password.resetRequest(data, [options], [callback])

Send a password reset confirmation

stelace.password.resetConfirm(data, [options], [callback])

Permissions

Check the permissions

stelace.permissions.check(data, [options], [callback])

Ratings

Get ratings’ stats

stelace.ratings.getStats([queryParams], [options], [callback])

List ratings

stelace.ratings.list([queryParams], [options], [callback])

Read a rating

stelace.ratings.read(ratingId, [queryParams], [options], [callback])

Create a rating

stelace.ratings.create(data, [options], [callback])

Update a rating

stelace.ratings.update(ratingId, data, [options], [callback])

Remove a rating

stelace.ratings.remove(ratingId, [options], [callback])

Roles

List roles (no pagination)

stelace.roles.list([queryParams], [options], [callback])

Read a role

stelace.roles.read(roleId, [queryParams], [options], [callback])

Create a role

stelace.roles.create(data, [options], [callback])

Update a role

stelace.roles.update(roleId, data, [options], [callback])

Remove a role

stelace.roles.remove(roleId, [options], [callback])

Saved searches

List saved searches

stelace.savedSearch.list([queryParams], [options], [callback])

Read a saved search

stelace.savedSearch.read(savedSearchId, [queryParams], [options], [callback])

Create a saved search

stelace.savedSearch.create(data, [options], [callback])

data is the object that is passed to POST /search endpoint (same endpoint as stelace.search.results method), but with two differences:

stelace.savedSearch.create method automatically sets save to true
the property name is required to create a saved search

Update a saved search

stelace.savedSearch.update(savedSearchId, data, [options], [callback])

Remove a saved search

stelace.savedSearch.remove(savedSearchId, [options], [callback])

Search

Search assets

stelace.search.results(data, [options], [callback])

Deprecated version: stelace.search.list(data, [options], [callback])

Tokens

Token check request

stelace.tokens.checkRequest(data, [options], [callback])

Token check confirm

stelace.tokens.checkConfirm(tokenId, [queryParams], [options], [callback])

Transactions

List transactions

stelace.transactions.list([queryParams], [options], [callback])

Read a transaction

stelace.transactions.read(transactionId, [queryParams], [options], [callback])

Preview a transaction

stelace.transactions.preview(data, [options], [callback])

Create a transaction

stelace.transactions.create(data, [options], [callback])

Update a transaction

stelace.transactions.update(transactionId, data, [options], [callback])

Create a transaction transition

stelace.transactions.createTransition(transactionId, data, [options], [callback])

Users

Check the username availability

stelace.users.checkAvailability(queryParams, [options], [callback])

List users

stelace.users.list([queryParams], [options], [callback])

Read a user

stelace.users.read(userId, [queryParams], [options], [callback])

Create a user

stelace.users.create(data, [options], [callback])

Update a user

stelace.users.update(userId, data, [options], [callback])

Remove a user

stelace.users.remove(userId, [options], [callback])

Make a user join an organization or update roles within

stelace.users.joinOrganizationOrUpdateRights(userId, organizationId, data, [options], [callback])

Remove a user from an organization

stelace.users.removeFromOrganization(userId, organizationId, [options], [callback])

Webhooks

List webhooks (no pagination)

stelace.webhooks.list([queryParams], [options], [callback])

Read a webhook

stelace.webhooks.read(webhookId, [queryParams], [options], [callback])

Create a webhook

stelace.webhooks.create(data, [options], [callback])

Update a webhook

stelace.webhooks.update(webhookId, data, [options], [callback])

Remove a webhook

stelace.webhooks.remove(webhookId, [options], [callback])

Workflows

List workflows (no pagination)

stelace.workflows.list([queryParams], [options], [callback])

Read a workflow

stelace.workflows.read(workflowId, [queryParams], [options], [callback])

Create a workflow

stelace.workflows.create(data, [options], [callback])

Update a workflow

stelace.workflows.update(workflowId, data, [options], [callback])

Remove a workflow

stelace.workflows.remove(workflowId, [options], [callback])

Name		Name	Last commit message	Last commit date
Latest commit History 470 Commits
.circleci		.circleci
.github		.github
.husky		.husky
lib		lib
test		test
testUtils		testUtils
.babelrc.js		.babelrc.js
.editorconfig		.editorconfig
.eslintignore		.eslintignore
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.lintstagedrc.json		.lintstagedrc.json
.npmrc		.npmrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
karma.base.conf.js		karma.base.conf.js
karma.conf.local.js		karma.conf.local.js
package.json		package.json
webpack.config.js		webpack.config.js
yarn.lock		yarn.lock

License

stelace/stelace.js

Folders and files

Latest commit

History

Repository files navigation

Stelace Javascript SDK

Core Features

Supported browsers and Node.js versions

Installation

Node

Browser

ES module

Script tag

Usage

Authentication

Token store

Refreshing tokens your way

Using Promises

Examining Responses

Options

Configuring Timeout

API version compatibility

Development

SDK documentation

API keys

List API keys

Read an API key

Create an API key

Update an API key

Remove an API key

Assets

List Assets

Read an Asset

Create an Asset

Update an Asset

Remove an Asset

Asset types

List Asset types (no pagination)

Read an Asset type

Create an Asset type

Update an Asset type

Remove an Asset type

Authentication

Login

Get current session info

Logout

User session expiration

Get tokens after SSO or social login

Check authentication information

Forward methods (advanced usage)

GET verb

POST verb

PUT verb

PATCH verb

DELETE verb

OPTIONS verb

Availability

Get availabilities graph

List availabilities

Create an availability

Update an availability

Remove an availability

Categories

List categories (no pagination)

Read a category

Create a category

Update a category

Remove a category

Config

Read config

Update config

Read private config

Update private config

Custom attributes

List custom attributes

Read a custom attribute

Create a custom attribute

Update a custom attribute

Remove a custom attribute