@signageos/sdk
v1.24.0
Published
Library which allows you to fully manage signageOS applets, devices, management & monitoring using JS.
Downloads
1,043
Readme
SDK Library
Library which allows you to fully manage signageOS applets, devices, management & monitoring using JS.
Installation and prerequisites
npm install @signageos/sdk
Environment variables
Mandatory ENV variables (when using SDK api/rest singleton - deprecated. Use factories createApiV1
or createApiV2
instead):
in .env
file:
# Organization API SECURITY TOKENS
SOS_AUTH_CLIENT_ID="...OAuthClientID..."
SOS_AUTH_SECRET="...OAuthSecret..."
# Account API SECURITY TOKENS
SOS_API_IDENTIFICATION="...apiSecurityTokenID..."
SOS_API_SECURITY_TOKEN="...apiSecurityToken..."
Optional ENV variable adjustment (with default values):
# REST API URL (default to the production server)
SOS_API_URL="https://api.signageos.io"
# How many times to retry request until it fails
SOS_REQUEST_MAX_ATTEMPTS="3"
# You can setup which profile to use when loading from `~/.sosrc` file (see details in https://github.com/signageos/cli#run-control-file)
SOS_PROFILE=
How to obtain Organization API SECURITY TOKENS
- Go to
Box
in the side menu selectOrganize
and sub menuOrganizations
- In organizations select your organization (or create new one)
- In top tabs select
API tokens
- Click on button
Add new token
and generate new values - Generated values can be used in
.env
fileSOS_AUTH_CLIENT_ID
isToken ID
andSOS_AUTH_SECRET
isToken Secret
How to obtain Account API SECURITY TOKENS
- Go to
Box
in the top navigation menu click on account icon - In drop down menu select
My profile
- Scroll to the bottom of the page, click on button
Add new token
and generate new values - Generate values can be used in
.env
fileSOS_API_IDENTIFICATION
isToken ID
andSOS_API_SECURITY_TOKEN
isToken Secret
You may read articles about setting up SDK & Rest API:
Please see the .env.dist
file where all mandatory ENV variables, required for SDK usage, are listed too.
REST API
Credentials in code
Just by setting ENV variables properly, you are ready to go and may use the api. If not ENV variables provided to
node.js app, it tries to get values from user's ~/.sosrc
which is configured by
@signageos/cli
dependency.
import { createApiV1 } from "@signageos/sdk";
const api = createApiV1(
{
url: 'https://api.signageos.io', // Optional
organizationAuth: {
clientId: '...OAuthClientID...',
secret: '...OAuthSecret...',
},
accountAuth: {
tokenId: '...apiSecurityTokenID...',
token: '...apiSecurityToken...',
},
},
);
// retrieves the list of all devices
const devices = await api.device.list();
// ...
import { createApiV2 } from "@signageos/sdk";
const api = createApiV2(
{
url: 'https://api.signageos.io', // Optional
organizationAuth: {
clientId: '...OAuthClientID...',
secret: '...OAuthSecret...',
},
accountAuth: {
tokenId: '...apiSecurityTokenID...',
token: '...apiSecurityToken...',
},
},
);
// retrieves the list of all devices
const devices = await api.device.list();
// ...
Credentials from ENV Variables
import { createApiV1 } from "@signageos/sdk";
// takes parameters from env vars
const api = createApiV1();
// retrieves the list of all devices
const devices = await api.device.list();
// ...
import { createApiV2 } from "@signageos/sdk";
// takes parameters from env vars
const api = createApiV2();
// retrieves the list of all devices
const devices = await api.device.list();
// ...
Documentation
The complete SDK documentation may be generated by typedoc by running the command:
$ npm i && npm run docs
Once generated, the docs
directory will contain the generated documentation.
The most useful documentation pages:
Development
Running the tests
Create .env file by running
cp .env.automated.test
and fill in the missing values. You have to ask the maintainer of the repository for the values.
Then,
- for unit tests run
npm run test
- for integration tests, run
npm run test-integration