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

1. Go to Box in the side menu select Organize and sub menu Organizations
2. In organizations select your organization (or create new one)
3. In top tabs select API tokens
4. Click on button Add new token and generate new values
5. Generated values can be used in .env file SOS_AUTH_CLIENT_ID is Token ID and SOS_AUTH_SECRET is Token Secret

How to obtain Account API SECURITY TOKENS

1. Go to Box in the top navigation menu click on account icon
2. In drop down menu select My profile
3. Scroll to the bottom of the page, click on button Add new token and generate new values
4. Generate values can be used in .env file SOS_API_IDENTIFICATION is Token ID and SOS_API_SECURITY_TOKEN is Token Secret

You may read articles about setting up SDK & Rest API:

• signageOS REST APIs for device management
• REST-API-Authentication
• Getting started with REST APIs

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();

// ...

Pagination

All list methods in the SDK return a PaginatedList which extends the standard JavaScript Array with pagination capabilities. The API enforces cursor-based pagination with a maximum page size.

Using Pagination

import { createApiV1 } from "@signageos/sdk";

const api = createApiV1();

// Get first page of applets
const applets = await api.applet.list({ limit: 50 });

// Get next page using getNextPage() method
const nextPage = await applets.getNextPage();

// Iterate through all pages
let currentPage = await api.applet.list({ limit: 100 });
do {
	for (const applet of currentPage) {
		console.log(applet.name);
	}
	currentPage = await currentPage.getNextPage();
} while (currentPage !== null);

Pagination Parameters

All list methods support the following pagination parameters:

• limit (number): Maximum number of items to return per page (default: 100, enforced by backend)
• descending (boolean): Sort results in descending order by createdAt (default: true -> newest first)

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:

• index

• Organization management

• Device management

• Applet management

• Timing management

• Timing Command management

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, run npm run test.