\n\n**What is Stelace?**\n\n[Stelace](https://stelace.com/) 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.\n\n## Core Features\n\n- Full Stelace API endpoints coverage\n- API key and Auth Tokens handling\n- ES6 modules / bundler support\n\n### Supported browsers and Node.js versions\n\n- Chrome\n- Firefox\n- Edge\n- Safari\n- IE11 (except when using pre-packaged [evergreen version](#script-tag))\n- Node.js (>=10.18)\n\nOther browsers with similar feature set should also work.\n\n## Installation\n\n```js\nnpm install stelace\n```\n\nThis package needs to be used with secret or publishable api keys you can find in Stelace Dashboard.\n\n### Node\n\n``` js\nconst { createInstance } = require('stelace')\nconst stelace = createInstance({ apiKey: 'seck_test_...' })\n\nconst asset = await stelace.assets.create({\n name: 'Car'\n})\n```\n\n\nWith callback\n\n``` js\nconst Stelace = require('stelace')\nconst stelace = Stelace.createInstance({ apiKey: 'seck_test_...' })\n\nstelace.assets.create({\n name: 'Car'\n}, function (err, asset) {\n err // null if no error occurred\n asset // the created asset object\n})\n```\n\n\n \n\n> **Warning**: secret apiKey `seck_...` must only be used in secure environments as it grants all endpoint permissions.\n\n### Browser\n\nFor browser you can either install (with npm/yarn) or add a `\n```\n\nYou can then use `stelace` global variable.\n\nWe offer a smaller build for modern browsers (excluding IE11 and Opera Mini in particular):\n\n```html\n\n```\n\nUnminified and map files are also [available](https://www.jsdelivr.com/package/npm/stelace).\n\n## Usage\n\n### Authentication\n\nA publishable api key identifies your platform and enables all publicly accessible endpoints.\n\nYou’ll often need to call endpoints as one of your authenticated platform `user`s (typically from your front-end).\n\nPublishable 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.\n\n``` js\nconst { createInstance } = require('stelace')\nconst stelace = createInstance({ apiKey: 'pubk_test_...' })\n\n// Login as the user 'foo@example.com'\nawait stelace.auth.login({\n username: 'foo@example.com',\n password: 'secretPassword'\n})\n\n// Any actions performed will be associated to this user\nawait stelace.assets.create(...)\n\n// Logout to destroy the current session\nawait stelace.auth.logout()\n```\n\nAfter successful login, the access and refresh tokens will be returned.\n\nStelace SDK handles the authentication for you and will automatically renew the access token when it's expired.\n\n\nCustom authentication\n\nAdvanced options are available for custom authentication workflows.\n\n#### Token store\n\nBy default, Stelace provides a default token store for the authentication tokens storage.\nTokens are stored into localStorage in browser environment and into memory in Node.js.\n\nIf custom storage is needed, a token store can be provided at initialization:\n\n```js\nconst myCustomTokenStore = {...}\nconst stelace = createInstance({ apiKey: 'pubk_test_...', tokenStore: myCustomTokenStore })\n```\n\nor at run-time:\n\n```js\nstelace.setTokenStore(myCustomTokenStore)\n```\n\nA token store must be an object implementing the following functions:\n\n- getTokens()\n- setTokens(tokens: `Object`)\n- removeTokens()\n\nFor convenience, we provide `stelace.getTokenStore()` if you need to perform some operation on tokens.\n\n#### Refreshing tokens your way\n\nIn some case (e.g. external authentication), you may need a custom workflow to refresh tokens.\n\n`beforeRefreshToken` function can also be provided at initialization:\n\n```js\nconst myBeforeRefreshToken = function (tokens, cb) {\n getNewTokens(tokens, function (err, newTokens) {\n cb(err, newTokens)\n })\n}\n\nconst stelace = createInstance({ apiKey: 'pubk_test_...', beforeRefreshToken: myBeforeRefreshToken })\n```\n\nor at run-time:\n\n```js\nstelace.setBeforeRefreshToken(myBeforeRefreshToken)\n```\n\nThe function `beforeRefreshToken` can also be a promise:\n\n```js\nconst myBeforeRefreshToken = async function (tokens) {\n const newTokens = await getNewTokens(tokens)\n return newTokens\n}\n```\n\nNote: Any token will be stored as is in token store.\n\n\n\n### Using Promises\n\nEach method request returns a promise (or `await` as above) that you can use in place of callbacks:\n\n``` js\n// Create an asset type and create an asset with it\nstelace.assetTypes.create({\n name: 'Renting',\n timeBased: true,\n infiniteStock: false\n}).then(function (assetType) {\n return stelace.assets.create({\n name: 'Car',\n assetTypeId: assetType.id\n })\n}).then(function (asset) {\n // Created asset\n}).catch(function (err) {\n // Handle this error\n})\n```\n\n### Examining Responses\n\nSome information about the response is provided in the `lastResponse` property as convenience:\n\n```js\nasset.lastResponse.requestId\nasset.lastResponse.statusCode\n```\n\nWhen pagination is available in list endpoints, you’ll directly get `results` array as response:\n\n```js\nconst assets = await stelace.assets.list()\nconsole.log(Array.isArray(assets)) // true\nconsole.log(assets.lastResponse.statusCode) // 200\nconsole.log(assets.paginationMeta.page) // 1\n```\n\nHere are the properties included in `paginationMeta`:\n\n```js\nassets.paginationMeta.nbResults\nassets.paginationMeta.nbPages\nassets.paginationMeta.page\nassets.paginationMeta.nbResultsPerPage\n```\n\nCurrently, the following list endpoints don't support pagination:\n- asset type\n- category\n- role\n- webhook\n- workflow\n\n### Options\n\nOptions are additional parameters that you can pass after the required arguments after any given method.\n\nAll methods can accept an optional `options` object containing one or more of the following:\n\n- `stelaceVersion` - use a specific Stelace API version for this request\n- `stelaceUserId` - perform the request as the specified user ID, needs specific permissions to do so\n- `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()`\n\nThis `options` object can be included as the last argument for any method (or second to last when using callbacks):\n\n```js\n// Only the category data object\nstelace.categories.create({\n name: 'Sport'\n})\n\n// The category data object and the options object\nstelace.categories.create({\n name: 'Sport'\n}, {\n stelaceVersion: '2018-07-30'\n})\n```\n\n### Configuring Timeout\n\nRequest timeout in case of network failure is configurable (the default is 30 seconds):\n\n``` js\nstelace.setTimeout(10000); // in ms (10 seconds)\n```\n\n## Development\n\nRun all tests:\n\n```bash\nnpm install\nnpm test\n```\n\nRun tests in browser environments (Chrome and Firefox):\n\n```bash\nnpm test:browser-local\n```\n\n\n## SDK documentation\n\nMost of the methods follow the same schema concerning arguments:\n\n**Id**: `string` - Object ID\n\n**queryParams**: `object` - Query parameters in GET requests (usually for pagination)\n\n**data**: `object` - Body of the request for POST/PATCH requests (usually for creation or update of an object)\n\n**options**: `object` - Options parameters described above\n\n**callback**: `function` - Callback function. Omit it when using promises\n\nThe optional arguments are within [brackets].\n\n\n### API keys\n\n#### List API keys\n\nstelace.apiKeys.list([queryParams], [options], [callback])\n\n#### Read an API key\n\nstelace.apiKeys.read(apiKeyId, [queryParams], [options], [callback])\n\n#### Create an API key\n\nstelace.apiKeys.create(data, [options], [callback])\n\n#### Update an API key\n\nstelace.apiKeys.update(apiKeyId, data, [options], [callback])\n\n#### Remove an API key\n\nstelace.apiKeys.remove(apiKeyId, [options], [callback])\n\n\n\n### Assets\n\n#### List Assets\n\nstelace.assets.list([queryParams], [options], [callback])\n\n#### Read an Asset\n\nstelace.assets.read(assetId, [queryParams], [options], [callback])\n\n#### Create an Asset\n\nstelace.assets.create(data, [options], [callback])\n\n#### Update an Asset\n\nstelace.assets.update(assetId, data, [options], [callback])\n\n#### Remove an Asset\n\nstelace.assets.remove(assetId, [options], [callback])\n\n\n\n### Asset types\n\n#### List Asset types (no pagination)\n\nstelace.assetTypes.list([queryParams], [options], [callback])\n\n#### Read an Asset type\n\nstelace.assetTypes.read(assetTypeId, [queryParams], [options], [callback])\n\n#### Create an Asset type\n\nstelace.assetTypes.create(data, [options], [callback])\n\n#### Update an Asset type\n\nstelace.assetTypes.update(assetTypeId, data, [options], [callback])\n\n#### Remove an Asset type\n\nstelace.assetTypes.remove(assetTypeId, [options], [callback])\n\n\n\n### Authentication\n\n#### Login\n\nstelace.auth.login(data, [options], [callback])\n\n#### Get current session info\n\nstelace.auth.info()\n\nReturns an object with the following properties:\n\n- **isAuthenticated**: `boolean`\n- **userId**: `string|null`\n\n#### Logout\n\nstelace.auth.logout()\n\n#### User session expiration\n\nTo detect when the user session has expired and handle it properly, you can listen to the following error event:\n```\nstelace.onError('userSessionExpired', function () {\n // In browser, you can notify users that they must reconnect\n // ...\n})\n```\n\nIf there are any authentication tokens, they will be automatically removed.\n\nTo stop listening to the event, you can unsubscribe by calling the returned function:\n```\nconst unsubscribe = stelace.onError('userSessionExpired', function () { ... })\nunsubscribe() // stops listening\n```\n\n#### Get tokens after SSO or social login\n\nstelace.auth.getTokens(data, [options], [callback])\n\n#### Check authentication information\n\nstelace.auth.check(data, [options], [callback])\n\n\n### Forward methods (advanced usage)\n\nFollowing methods are provided to hit custom endpoints with Stelace authentication headers.\nThis is especially useful if you need to call external endpoints with custom logic, e.g. using serverless lambda functions.\n\n`url` can be a relative path to Stelace [REST API endpoints](https://docs.api.stelace.com) or an absolute external URL.\nStelace API endpoint (relative) path is equivalent to using the equivalent SDK method, like:\n\n```js\nstelace.users.create(data)\n// same as\nstelace.forward.post('/users', data)\n```\n\n`forward.method`s map to corresponding HTTP verbs.\n\n#### GET verb\n\nstelace.forward.get(url, [callback])\n\n#### POST verb\n\nstelace.forward.post(url, [data], [callback])\n\n#### PUT verb\n\nstelace.forward.put(url, [data], [callback])\n\n#### PATCH verb\n\nstelace.forward.patch(url, [data], [callback])\n\n#### DELETE verb\n\nstelace.forward.del(url, [callback])\n\n#### OPTIONS verb\n\nstelace.forward.options(url, [callback])\n\n\n\n### Availability\n\n#### Get availabilities graph\n\nstelace.availabilities.getGraph([queryParams], [options], [callback])\n\n#### List availabilities\n\nstelace.availabilities.list([queryParams], [options], [callback])\n\n#### Create an availability\n\nstelace.availabilities.create(data, [options], [callback])\n\n#### Update an availability\n\nstelace.availabilities.update(availabilityId, data, [options], [callback])\n\n#### Remove an availability\n\nstelace.availabilities.remove(availabilityId, [options], [callback])\n\n\n\n### Categories\n\n#### List categories (no pagination)\n\nstelace.categories.list([queryParams], [options], [callback])\n\n#### Read a category\n\nstelace.categories.read(categoryId, [queryParams], [options], [callback])\n\n#### Create a category\n\nstelace.categories.create(data, [options], [callback])\n\n#### Update a category\n\nstelace.categories.update(categoryId, data, [options], [callback])\n\n#### Remove a category\n\nstelace.categories.remove(categoryId, [options], [callback])\n\n\n\n### Config\n\n#### Read config\n\nstelace.config.read([options], [callback])\n\n#### Update config\n\nstelace.config.update([data], [options], [callback])\n\n#### Read private config\n\nstelace.config.readPrivate([options], [callback])\n\n#### Update private config\n\nstelace.config.updatePrivate([data], [options], [callback])\n\n\n\n### Custom attributes\n\n#### List custom attributes\n\nstelace.customAttributes.list([queryParams], [options], [callback])\n\n#### Read a custom attribute\n\nstelace.customAttributes.read(customAttributeId, [queryParams], [options], [callback])\n\n#### Create a custom attribute\n\nstelace.customAttributes.create(data, [options], [callback])\n\n#### Update a custom attribute\n\nstelace.customAttributes.update(customAttributeId, data, [options], [callback])\n\n#### Remove a custom attribute\n\nstelace.customAttributes.remove(customAttributeId, [options], [callback])\n\n\n\n### Documents\n\n#### Get documents’ stats\n\nstelace.documents.getStats([queryParams], [options], [callback])\n\n#### List documents\n\nstelace.documents.list([queryParams], [options], [callback])\n\n#### Read a document\n\nstelace.documents.read(documentId, [queryParams], [options], [callback])\n\n#### Create a document\n\nstelace.documents.create(data, [options], [callback])\n\n#### Update a document\n\nstelace.documents.update(documentId, data, [options], [callback])\n\n#### Remove a document\n\nstelace.documents.remove(documentId, [options], [callback])\n\n\n\n### Entries\n\n#### List entries\n\nstelace.entries.list([queryParams], [options], [callback])\n\n#### Read an entry\n\nstelace.entries.read(entryId, [queryParams], [options], [callback])\n\n#### Create an entry\n\nstelace.entries.create(data, [options], [callback])\n\n#### Update an entry\n\nstelace.entries.update(entryId, data, [options], [callback])\n\n#### Remove an entry\n\nstelace.entries.remove(entryId, [options], [callback])\n\n\n\n### Events\n\n#### Get events’ stats\n\nstelace.events.getStats([queryParams], [options], [callback])\n\n#### List events\n\nstelace.events.list([queryParams], [options], [callback])\n\n#### Read an event\n\nstelace.events.read(eventId, [queryParams], [options], [callback])\n\n#### Create an event\n\nstelace.events.create(data, [options], [callback])\n\n\n\n### Messages\n\n#### List messages\n\nstelace.messages.list([queryParams], [options], [callback])\n\n#### Read a message\n\nstelace.messages.read(messageId, [queryParams], [options], [callback])\n\n#### Create a message\n\nstelace.messages.create(data, [options], [callback])\n\n#### Update a message\n\nstelace.messages.update(messageId, data, [options], [callback])\n\n#### Remove a message\n\nstelace.messages.remove(messageId, [options], [callback])\n\n\n\n### Orders\n\n#### List orders\n\nstelace.orders.list([queryParams], [options], [callback])\n\n#### Read an order\n\nstelace.orders.read(orderId, [queryParams], [options], [callback])\n\n#### Preview an order\n\nstelace.orders.preview(data, [options], [callback])\n\n#### Create an order\n\nstelace.orders.create(data, [options], [callback])\n\n#### Update an order\n\nstelace.orders.update(orderId, data, [options], [callback])\n\n\n\n### Order lines\n\n#### Read an order line\n\nstelace.orderLines.read(orderLineId, [queryParams], [options], [callback])\n\n#### Create an order line\n\nstelace.orderLines.create(data, [options], [callback])\n\n#### Update an order line\n\nstelace.orderLines.update(orderLineId, data, [options], [callback])\n\n\n\n### Order moves\n\n#### Read an order move\n\nstelace.orderMoves.read(orderMoveId, [queryParams], [options], [callback])\n\n#### Create an order move\n\nstelace.orderMoves.create(data, [options], [callback])\n\n#### Update an order move\n\nstelace.orderMoves.update(orderMoveId, data, [options], [callback])\n\n\n\n### Password\n\n#### Change the password\n\nstelace.password.change(data, [options], [callback])\n\n#### Send a password reset request\n\nstelace.password.resetRequest(data, [options], [callback])\n\n#### Send a password reset confirmation\n\nstelace.password.resetConfirm(data, [options], [callback])\n\n\n\n### Permissions\n\n#### Check the permissions\n\nstelace.permissions.check(data, [options], [callback])\n\n\n\n### Ratings\n\n#### Get ratings’ stats\n\nstelace.ratings.getStats([queryParams], [options], [callback])\n\n#### List ratings\n\nstelace.ratings.list([queryParams], [options], [callback])\n\n#### Read a rating\n\nstelace.ratings.read(ratingId, [queryParams], [options], [callback])\n\n#### Create a rating\n\nstelace.ratings.create(data, [options], [callback])\n\n#### Update a rating\n\nstelace.ratings.update(ratingId, data, [options], [callback])\n\n#### Remove a rating\n\nstelace.ratings.remove(ratingId, [options], [callback])\n\n\n\n### Roles\n\n#### List roles (no pagination)\n\nstelace.roles.list([queryParams], [options], [callback])\n\n#### Read a role\n\nstelace.roles.read(roleId, [queryParams], [options], [callback])\n\n#### Create a role\n\nstelace.roles.create(data, [options], [callback])\n\n#### Update a role\n\nstelace.roles.update(roleId, data, [options], [callback])\n\n#### Remove a role\n\nstelace.roles.remove(roleId, [options], [callback])\n\n\n\n### Saved searches\n\n#### List saved searches\n\nstelace.savedSearch.list([queryParams], [options], [callback])\n\n#### Read a saved search\n\nstelace.savedSearch.read(savedSearchId, [queryParams], [options], [callback])\n\n#### Create a saved search\n\nstelace.savedSearch.create(data, [options], [callback])\n\n`data` is the object that is passed to `POST /search` endpoint (same endpoint as `stelace.search.results` method), but with two differences:\n- `stelace.savedSearch.create` method automatically sets `save` to `true`\n- the property `name` is required to create a saved search\n\n#### Update a saved search\n\nstelace.savedSearch.update(savedSearchId, data, [options], [callback])\n\n#### Remove a saved search\n\nstelace.savedSearch.remove(savedSearchId, [options], [callback])\n\n\n\n### Search\n\n#### Search assets\n\nstelace.search.results(data, [options], [callback])\n\nDeprecated version:\nstelace.search.list(data, [options], [callback])\n\n\n\n### Tokens\n\n#### Token check request\n\nstelace.tokens.checkRequest(data, [options], [callback])\n\n#### Token check confirm\n\nstelace.tokens.checkConfirm(tokenId, [queryParams], [options], [callback])\n\n\n\n### Transactions\n\n#### List transactions\n\nstelace.transactions.list([queryParams], [options], [callback])\n\n#### Read a transaction\n\nstelace.transactions.read(transactionId, [queryParams], [options], [callback])\n\n#### Preview a transaction\n\nstelace.transactions.preview(data, [options], [callback])\n\n#### Create a transaction\n\nstelace.transactions.create(data, [options], [callback])\n\n#### Update a transaction\n\nstelace.transactions.update(transactionId, data, [options], [callback])\n\n#### Create a transaction transition\n\nstelace.transactions.createTransition(transactionId, data, [options], [callback])\n\n\n\n### Users\n\n#### Check the username availability\n\nstelace.users.checkAvailability(queryParams, [options], [callback])\n\n#### List users\n\nstelace.users.list([queryParams], [options], [callback])\n\n#### Read a user\n\nstelace.users.read(userId, [queryParams], [options], [callback])\n\n#### Create a user\n\nstelace.users.create(data, [options], [callback])\n\n#### Update a user\n\nstelace.users.update(userId, data, [options], [callback])\n\n#### Remove a user\n\nstelace.users.remove(userId, [options], [callback])\n\n#### Make a user join an organization or update roles within\n\nstelace.users.joinOrganizationOrUpdateRights(userId, organizationId, data, [options], [callback])\n\n#### Remove a user from an organization\n\nstelace.users.removeFromOrganization(userId, organizationId, [options], [callback])\n\n\n\n### Webhooks\n\n#### List webhooks (no pagination)\n\nstelace.webhooks.list([queryParams], [options], [callback])\n\n#### Read a webhook\n\nstelace.webhooks.read(webhookId, [queryParams], [options], [callback])\n\n#### Create a webhook\n\nstelace.webhooks.create(data, [options], [callback])\n\n#### Update a webhook\n\nstelace.webhooks.update(webhookId, data, [options], [callback])\n\n#### Remove a webhook\n\nstelace.webhooks.remove(webhookId, [options], [callback])\n\n\n\n### Workflows\n\n#### List workflows (no pagination)\n\nstelace.workflows.list([queryParams], [options], [callback])\n\n#### Read a workflow\n\nstelace.workflows.read(workflowId, [queryParams], [options], [callback])\n\n#### Create a workflow\n\nstelace.workflows.create(data, [options], [callback])\n\n#### Update a workflow\n\nstelace.workflows.update(workflowId, data, [options], [callback])\n\n#### Remove a workflow\n\nstelace.workflows.remove(workflowId, [options], [callback])\n","readmeFilename":"README.md"}
![\"CI](\"https://circleci.com/gh/stelace/stelace.js.svg?style=svg\")
\n\n \n ![\"MIT](\"https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square\"){kind=icon}
\n \n\n \n ![\"GZIP](\"http://img.badgesize.io/https://cdn.jsdelivr.net/npm/stelace/dist/stelace.evergreen.min.js?compression=gzip&style=flat-square\")
\n \n\n \n ![](\"https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=flat-square\"){kind=icon}
\n \n