npm package: @signageos/sdk
Description: Library which allows you to fully manage signageOS applets, devices, management & monitoring using JS.
Author: signageOS
Latest version: 2.5.0

# SDK Library

> ⚠️ **REST API Wrapper - Maintenance Mode**: The REST API wrapper portion of this SDK is no longer receiving new features. Existing functionality will continue to work and backward compatibility is maintained. For new REST API integrations, we recommend using the [REST API](https://docs.signageos.io/hc/en-us/articles/4405231278482) directly with proper OpenAPI specifications.

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](https://docs.signageos.io/hc/en-us/articles/4405231278482)
- [REST-API-Authentication](https://docs.signageos.io/hc/en-us/articles/4405239033234)
- [Getting started with REST APIs](https://docs.signageos.io/hc/en-us/articles/4405231428114)

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`](https://github.com/signageos/cli) dependency.

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

// ...
```

```javascript
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

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

// ...
```

```javascript
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

```javascript
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](https://typedoc.org/) 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](https://public.docs.signageos.io/sdk/latest/index.html)

- [Organization management](https://public.docs.signageos.io/sdk/latest/classes/organizationmanagement.html)
- [Device management](https://public.docs.signageos.io/sdk/latest/classes/devicemanagement.html)
- [Applet management](https://public.docs.signageos.io/sdk/latest/classes/appletmanagement.html)
- [Timing management](https://public.docs.signageos.io/sdk/latest/classes/timingmanagement.html)
- [Timing Command management](https://public.docs.signageos.io/sdk/latest/classes/timingcommandmanagement.html)