@signageos/cli 2.4.1 → 2.6.0-rc.0

package/dist/Runner/runnerFacede.d.ts

@@ -0,0 +1,15 @@
+import RestApi from '@signageos/sdk/dist/RestApi/RestApi';
+import { PlatformConfig } from '../CustomScript/customScriptFacade';
+import { IRunnerVersion } from '@signageos/sdk/dist/RestApi/Runner/Version/IRunnerVersion';
+import z from 'zod';
+import { ConfigSchema } from '../Plugin/pluginFacade';
+export declare function ensureRunnerVersion(restApi: RestApi, config: RunnerConfig, schema: any): Promise<IRunnerVersion>;
+export declare function uploadCode({ restApi, workDir, platform, config, runnerVersion, }: {
+    restApi: RestApi;
+    workDir: string;
+    platform: string;
+    config: PlatformConfig;
+    runnerVersion: IRunnerVersion;
+}): Promise<void>;
+export declare function loadSchemas(workDir: string): Promise<any>;
+export type RunnerConfig = z.infer<typeof ConfigSchema>;

package/dist/Runner/runnerFacede.js

@@ -0,0 +1,234 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureRunnerVersion = ensureRunnerVersion;
+exports.uploadCode = uploadCode;
+exports.loadSchemas = loadSchemas;
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const fs = __importStar(require("fs-extra"));
+const prompts_1 = __importDefault(require("prompts"));
+const chalk_1 = __importDefault(require("chalk"));
+const log_1 = require("@signageos/sdk/dist/Console/log");
+const archive_1 = require("../Lib/archive");
+const fileSystem_1 = require("../Lib/fileSystem");
+const runtimeFileSystem_1 = require("@signageos/sdk/dist/Development/runtimeFileSystem");
+const customScriptFacade_1 = require("../CustomScript/customScriptFacade");
+const PLUGIN_BUILDS_DIRNAME = 'plugin_builds';
+function ensureRunnerVersion(restApi, config, schema) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const runner = yield ensureRunner(restApi, config);
+        const runnerVersion = yield restApi.runner.version.get({ runnerUid: runner.uid, version: config.version });
+        if (runnerVersion) {
+            return runnerVersion;
+        }
+        const response = yield (0, prompts_1.default)({
+            type: 'confirm',
+            name: 'newVersion',
+            message: `Do you want to create new runner version ${config.version}?`,
+        });
+        if (!response.newVersion) {
+            throw new Error('Runner version creation was canceled.');
+        }
+        (0, log_1.log)('info', chalk_1.default.yellow(`Creating Runner version ${config.version}`));
+        return yield restApi.runner.version.create({
+            runnerUid: runner.uid,
+            version: config.version,
+            description: config.description,
+            input: schema.input,
+            output: schema.output,
+            telemetry: schema.telemetry,
+            configDefinition: config.configDefinition,
+        });
+    });
+}
+function ensureRunner(restApi, config) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (config.uid) {
+            const runner = yield restApi.runner.get(config.uid);
+            if (runner) {
+                yield restApi.runner.update(runner.uid, {
+                    name: config.name,
+                    title: config.name,
+                    description: config.description,
+                });
+                return runner;
+            }
+            throw new Error(`Runner with uid "${config.uid}" not found`);
+        }
+        const response = yield (0, prompts_1.default)({
+            type: 'confirm',
+            name: 'create',
+            message: `Runner "${config.name}" does not exist. Do you want to create it?`,
+        });
+        if (!response.create) {
+            throw new Error('Runner upload was canceled.');
+        }
+        (0, log_1.log)('info', chalk_1.default.yellow(`Creating Runner "${config.name}"`));
+        const createdRunner = yield restApi.runner.create({
+            name: config.name,
+            title: config.name,
+            description: config.description,
+        });
+        // TODO ask for permission or read from CLI arg
+        (0, log_1.log)('info', chalk_1.default.yellow('Adding Runner uid to the config file'));
+        yield (0, customScriptFacade_1.addToConfigFile)(process.cwd(), { uid: createdRunner.uid });
+        return createdRunner;
+    });
+}
+function uploadCode(_a) {
+    return __awaiter(this, arguments, void 0, function* ({ restApi, workDir, platform, config, runnerVersion, }) {
+        const { mainFile, runtime } = config;
+        const codeArchive = yield generateRunnerPlatformCodeArchive(workDir, config, runnerVersion, platform);
+        const runnerVersionPlatform = yield restApi.runner.version.platform.get({
+            runnerUid: runnerVersion.runnerUid,
+            version: runnerVersion.version,
+            platform,
+        });
+        if ((runnerVersionPlatform === null || runnerVersionPlatform === void 0 ? void 0 : runnerVersionPlatform.md5Checksum) === codeArchive.md5Checksum) {
+            (0, log_1.log)('info', chalk_1.default.yellow(`Skipping upload for ${platform} - no changes detected`));
+            return;
+        }
+        try {
+            (0, log_1.log)('info', chalk_1.default.yellow(`Uploading files for ${platform}`));
+            yield uploadCodeArchive({
+                restApi,
+                runnerVersion,
+                platform,
+                codeArchive,
+            });
+            yield restApi.runner.version.platform.update({
+                runnerUid: runnerVersion.runnerUid,
+                version: runnerVersion.version,
+                platform,
+                mainFile,
+                runtime,
+                md5Checksum: codeArchive.md5Checksum,
+            });
+        }
+        finally {
+            yield codeArchive.delete();
+        }
+    });
+}
+function uploadCodeArchive(_a) {
+    return __awaiter(this, arguments, void 0, function* ({ restApi, runnerVersion, platform, codeArchive, }) {
+        const filePath = codeArchive.filePath;
+        const fileSize = (yield fs.stat(filePath)).size;
+        const fileStream = fs.createReadStream(filePath);
+        yield restApi.runner.version.platform.archive.upload({
+            runnerUid: runnerVersion.runnerUid,
+            version: runnerVersion.version,
+            platform,
+            md5Checksum: codeArchive.md5Checksum,
+            size: fileSize,
+            stream: fileStream,
+        });
+    });
+}
+/**
+ * Generates an archive with the code for a particular platform, defined by the provided configuration.
+ *
+ * Archive is generated and stored in the runtime /tmp/signageos/runner_scripts_builds/:uid/:version/ directory.
+ * After archive isn't needed anymore, it should be deleted using the delete method.
+ */
+function generateRunnerPlatformCodeArchive(workDir, config, runnerVersion, platform) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const buildsDir = yield ensureBuildsDirectory(runnerVersion);
+        const archiveFileName = `${platform}.zip`;
+        const archiveFilePath = path.join(buildsDir, archiveFileName);
+        yield (0, archive_1.generateZip)(workDir, config.rootDir, archiveFilePath);
+        const md5Checksum = yield (0, fileSystem_1.getFileMD5Checksum)(archiveFilePath);
+        return {
+            filePath: archiveFilePath,
+            md5Checksum,
+            delete() {
+                return __awaiter(this, void 0, void 0, function* () {
+                    yield fs.unlink(archiveFilePath);
+                });
+            },
+        };
+    });
+}
+/**
+ * Ensure that the runtime directory for runner script version exists in the current working directory.
+ *
+ * This directory is used to store temporary files generated by the CLI.
+ */
+function ensureBuildsDirectory(runnerVersion) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const runtimeDir = yield ensureRuntimeDir();
+        const buildsDir = path.join(runtimeDir, runnerVersion.runnerUid, runnerVersion.version);
+        yield fs.ensureDir(buildsDir);
+        return buildsDir;
+    });
+}
+/**
+ * Ensure that the runtime directory exists in the current working directory.
+ *
+ * This directory is used to store temporary files generated by the CLI.
+ */
+function ensureRuntimeDir() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const runtimeDir = path.join(os.tmpdir(), runtimeFileSystem_1.RUNTIME_DIRNAME, PLUGIN_BUILDS_DIRNAME);
+        yield fs.ensureDir(runtimeDir);
+        return runtimeDir;
+    });
+}
+function loadSchemas(workDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const filePath = getConfigFilePath(workDir);
+        if (!(yield fs.pathExists(filePath))) {
+            throw new Error(`Config file schema.json not found`);
+        }
+        const fileContent = fs.readFileSync(filePath, 'utf-8');
+        return JSON.parse(fileContent);
+    });
+}
+function getConfigFilePath(workDir) {
+    return path.join(workDir, 'schema.json');
+}

package/dist/Timing/List/timingListCommand.d.ts

@@ -2,7 +2,7 @@ import { CommandLineOptions } from '../../Command/commandDefinition';
 declare const OPTION_LIST: readonly [{
     readonly name: "no-default-organization";
     readonly type: BooleanConstructor;
-    readonly description: "Prevent using the defaultOrganizationUid from ~/.sosrc which were set using command sos organization set-default";
+    readonly description: "Prevent using the defaultOrganizationUid from ~/.sosrc";
 }, {
     readonly name: "organization-uid";
     readonly type: StringConstructor;
@@ -12,13 +12,37 @@ declare const OPTION_LIST: readonly [{
     readonly type: StringConstructor;
     readonly description: "Device UID";
 }];
+/**
+ * Retrieves and displays all timing configurations that are currently assigned
+ * to a specific device. Timing configurations define when and how content
+ * (applets) should be displayed on devices, including scheduling and duration settings.
+ *
+ * @group Management:1
+ *
+ * @example
+ * ```bash
+ * # List timings for a specific device
+ * sos timing list --device-uid device123
+ *
+ * # List timings with organization override
+ * sos timing list --device-uid device123 --organization-uid org456
+ * ```
+ *
+ * @throws {Error} When device cannot be found or accessed
+ *
+ * @throws {Error} When organization access is denied
+ *
+ * @throws {Error} When timing list retrieval fails
+ *
+ * @since 0.3.0
+ */
 export declare const timingList: {
     name: "list";
     description: string;
     optionList: readonly [{
         readonly name: "no-default-organization";
         readonly type: BooleanConstructor;
-        readonly description: "Prevent using the defaultOrganizationUid from ~/.sosrc which were set using command sos organization set-default";
+        readonly description: "Prevent using the defaultOrganizationUid from ~/.sosrc";
     }, {
         readonly name: "organization-uid";
         readonly type: StringConstructor;

package/dist/Timing/List/timingListCommand.js

@@ -21,9 +21,33 @@ const helper_1 = require("../../helper");
 const commandDefinition_1 = require("../../Command/commandDefinition");
 const Debug = (0, debug_1.default)('@signageos/cli:Timing:list');
 const OPTION_LIST = [organizationFacade_1.NO_DEFAULT_ORGANIZATION_OPTION, organizationFacade_1.ORGANIZATION_UID_OPTION, deviceFacade_1.DEVICE_UID_OPTION];
+/**
+ * Retrieves and displays all timing configurations that are currently assigned
+ * to a specific device. Timing configurations define when and how content
+ * (applets) should be displayed on devices, including scheduling and duration settings.
+ *
+ * @group Management:1
+ *
+ * @example
+ * ```bash
+ * # List timings for a specific device
+ * sos timing list --device-uid device123
+ *
+ * # List timings with organization override
+ * sos timing list --device-uid device123 --organization-uid org456
+ * ```
+ *
+ * @throws {Error} When device cannot be found or accessed
+ *
+ * @throws {Error} When organization access is denied
+ *
+ * @throws {Error} When timing list retrieval fails
+ *
+ * @since 0.3.0
+ */
 exports.timingList = (0, commandDefinition_1.createCommandDefinition)({
     name: 'list',
-    description: 'List timings assigned to device',
+    description: 'List timing configurations assigned to a device',
     optionList: OPTION_LIST,
     commands: [],
     run(options) {
@@ -36,7 +60,7 @@ exports.timingList = (0, commandDefinition_1.createCommandDefinition)({
             const timings = yield restApi.timing.getList({
                 deviceUid,
             });
-            console.log(chalk_1.default.yellow(JSON.stringify(timings, undefined, 2)));
+            console.info(chalk_1.default.yellow(JSON.stringify(timings, undefined, 2)));
         });
     },
 });

package/dist/Timing/timingCommand.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Provides commands for managing timing configurations that control when and how
+ * applets are displayed on signageOS devices. Timing configurations define the
+ * relationship between devices, applets, and scheduling parameters.
+ *
+ * @group Management:4
+ *
+ * @example
+ * ```bash
+ * # List timing configurations
+ * sos timing list
+ * ```
+ *
+ * @since 0.3.0
+ */
 export declare const timing: {
     name: "timing";
     description: string;
@@ -8,7 +23,7 @@ export declare const timing: {
         optionList: readonly [{
             readonly name: "no-default-organization";
             readonly type: BooleanConstructor;
-            readonly description: "Prevent using the defaultOrganizationUid from ~/.sosrc which were set using command sos organization set-default";
+            readonly description: "Prevent using the defaultOrganizationUid from ~/.sosrc";
         }, {
             readonly name: "organization-uid";
             readonly type: StringConstructor;
@@ -22,7 +37,7 @@ export declare const timing: {
         run(options: import("../Command/commandDefinition").CommandLineOptions<readonly [{
             readonly name: "no-default-organization";
             readonly type: BooleanConstructor;
-            readonly description: "Prevent using the defaultOrganizationUid from ~/.sosrc which were set using command sos organization set-default";
+            readonly description: "Prevent using the defaultOrganizationUid from ~/.sosrc";
         }, {
             readonly name: "organization-uid";
             readonly type: StringConstructor;

package/dist/Timing/timingCommand.js

@@ -12,6 +12,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.timing = void 0;
 const commandDefinition_1 = require("../Command/commandDefinition");
 const timingListCommand_1 = require("./List/timingListCommand");
+/**
+ * Provides commands for managing timing configurations that control when and how
+ * applets are displayed on signageOS devices. Timing configurations define the
+ * relationship between devices, applets, and scheduling parameters.
+ *
+ * @group Management:4
+ *
+ * @example
+ * ```bash
+ * # List timing configurations
+ * sos timing list
+ * ```
+ *
+ * @since 0.3.0
+ */
 exports.timing = (0, commandDefinition_1.createCommandDefinition)({
     name: 'timing',
     description: 'Timing management',

package/dist/helper.d.ts

@@ -1,7 +1,7 @@
-import fetch, { RequestInit } from 'node-fetch';
 import RestApi from '@signageos/sdk/dist/RestApi/RestApi';
 import { ApiVersions } from '@signageos/sdk/dist/RestApi/apiVersions';
 import { IConfig } from '@signageos/sdk/dist/SosHelper/sosControlHelper';
+type RequestInit = globalThis.RequestInit;
 interface ICredentials {
     oauthClientId: string;
     oauthClientSecret: string;
@@ -27,9 +27,9 @@ export interface IOptions {
 }
 export declare function createOptions(method: 'POST' | 'GET' | 'PUT' | 'DELETE', options: IOptions, data?: any): RequestInit;
 export declare function createUri(options: IOptions, resource: string, queryParams?: any): string;
-export declare function getResource(options: IOptions, path: string, query?: any): Promise<fetch.Response>;
-export declare function postResource(options: IOptions, path: string, query?: any, data?: any): Promise<fetch.Response>;
-export declare function putResource(options: IOptions, path: string, query?: any, data?: any): Promise<fetch.Response>;
-export declare function deleteResource(options: IOptions, path: string): Promise<fetch.Response>;
+export declare function getResource(options: IOptions, path: string, query?: any): Promise<Response>;
+export declare function postResource(options: IOptions, path: string, query?: any, data?: any): Promise<Response>;
+export declare function putResource(options: IOptions, path: string, query?: any, data?: any): Promise<Response>;
+export declare function deleteResource(options: IOptions, path: string): Promise<Response>;
 export declare function deserializeJSON(_key: string, value: any): any;
 export {};

package/dist/helper.js

@@ -25,9 +25,7 @@ exports.postResource = postResource;
 exports.putResource = putResource;
 exports.deleteResource = deleteResource;
 exports.deserializeJSON = deserializeJSON;
-const node_fetch_1 = __importDefault(require("node-fetch"));
 const querystring_1 = require("querystring");
-// import { RequestInit } from 'node-fetch';
 const RestApi_1 = __importDefault(require("@signageos/sdk/dist/RestApi/RestApi"));
 const runControlHelper_1 = require("./RunControl/runControlHelper");
 const apiVersions_1 = require("@signageos/sdk/dist/RestApi/apiVersions");
@@ -97,16 +95,16 @@ function createUri(options, resource, queryParams) {
     return [options.url, options.version, resource].join('/') + (typeof queryParams !== 'undefined' ? '?' + (0, querystring_1.stringify)(queryParams) : '');
 }
 function getResource(options, path, query) {
-    return (0, node_fetch_1.default)(createUri(options, path, query), createOptions('GET', options));
+    return fetch(createUri(options, path, query), createOptions('GET', options));
 }
 function postResource(options, path, query, data) {
-    return (0, node_fetch_1.default)(createUri(options, path, query), createOptions('POST', options, data));
+    return fetch(createUri(options, path, query), createOptions('POST', options, data));
 }
 function putResource(options, path, query, data) {
-    return (0, node_fetch_1.default)(createUri(options, path, query), createOptions('PUT', options, data));
+    return fetch(createUri(options, path, query), createOptions('PUT', options, data));
 }
 function deleteResource(options, path) {
-    return (0, node_fetch_1.default)(createUri(options, path), createOptions('DELETE', options));
+    return fetch(createUri(options, path), createOptions('DELETE', options));
 }
 function deserializeJSON(_key, value) {
     if (typeof value === 'string') {

package/dist/index.js

@@ -20,12 +20,36 @@ const deviceCommand_1 = require("./Device/deviceCommand");
 const generalCommand_1 = require("./generalCommand");
 const commandDefinition_1 = require("./Command/commandDefinition");
 const customScriptCommand_1 = require("./CustomScript/customScriptCommand");
+const pluginCommand_1 = require("./Plugin/pluginCommand");
+const runnerCommand_1 = require("./Runner/runnerCommand");
 const autocompleteCommand_1 = require("./Command/Autocomplete/autocompleteCommand");
+/**
+ * The root command for the signageOS CLI tool that provides comprehensive management
+ * capabilities for applets, devices, organizations, and other signageOS resources.
+ * This command serves as the entry point for all CLI operations and coordinates
+ * access to all available command groups.
+ *
+ * @example
+ * ```bash
+ * # Show help and available commands
+ * sos --help
+ *
+ * # Show version information
+ * sos --version
+ *
+ * # Use custom API endpoint
+ * sos --api-url https://api.custom.signageos.io applet list
+ * ```
+ *
+ * @see {@link https://developers.signageos.io/docs/cli-setup/ CLI Setup}
+ *
+ * @since 0.1.0
+ */
 const index = (0, commandDefinition_1.createCommandDefinition)({
     name: 'sos',
-    description: 'signageOS',
+    description: 'SignageOS CLI - The central command-line tool for deploying, managing, and debugging signageOS projects and devices',
     optionList: generalCommand_1.GENERAL_OPTION_LIST,
-    commands: [appletCommand_1.applet, loginCommand_1.login, organizationCommand_1.organization, timingCommand_1.timing, firmwareCommand_1.firmware, deviceCommand_1.device, customScriptCommand_1.customScript, autocompleteCommand_1.autocomplete],
+    commands: [appletCommand_1.applet, loginCommand_1.login, organizationCommand_1.organization, timingCommand_1.timing, firmwareCommand_1.firmware, deviceCommand_1.device, customScriptCommand_1.customScript, pluginCommand_1.plugin, runnerCommand_1.runner, autocompleteCommand_1.autocomplete],
     run() {
         return __awaiter(this, void 0, void 0, function* () {
             throw new Error('Unknown command');

package/docs/applet/build/index.md

@@ -0,0 +1,74 @@
+---
+id: applet-build-index
+title: build
+sidebar_position: 22
+---
+# build
+
+Build applet locally for production deployment.
+
+
+## Description
+
+Builds the applet into a distributable package using the signageOS SDK build system.
+The build process compiles and bundles the applet code, assets, and dependencies
+into a zip archive ready for upload to the signageOS platform.
+
+## Usage
+
+```bash
+sos applet build [options]
+```
+
+## Options
+
+| Option                      | Description                                                      |
+| --------------------------- | ---------------------------------------------------------------- |
+| `--no-default-organization` | Prevent using the defaultOrganizationUid from ~/.sosrc (boolean) |
+| `--organization-uid`        | Organization UID (string)                                        |
+| `--applet-uid`              | Applet UID (string)                                              |
+
+## Examples
+
+```bash
+# Build applet in current directory
+sos applet build
+
+# Build with specific organization
+sos applet build --organization-uid abc123def456
+
+# Build with specific applet UID
+sos applet build --applet-uid my-applet-uid
+```
+
+## Since
+
+1.2.0
+
+## Global Options
+
+All commands support the following global options:
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--help` | `-h` | Display help information for any command |
+| `--version` | `-v` | Display the installed version of the CLI |
+| `--api-url` | `-u` | Override the API URL for REST requests |
+| `--profile` | | Use a specific profile from ~/.sosrc config |
+
+### Examples
+
+```bash
+# Show version
+sos --version
+
+# Get help for any command
+sos applet --help
+sos applet upload --help
+
+# Use custom API endpoint
+sos --api-url https://api.example.com applet upload
+
+# Use specific profile
+sos --profile production organization list
+```