@signageos/front-applet 7.1.1 → 8.0.0

package/docs/fpath/index.md

@@ -0,0 +1,316 @@
+# fpath
+
+fpath utility mirrors node path module, but accepts IFilePath type instead of strings.
+
+Not implemented functions:
+- format
+- matchesGlob
+- parse
+- relative
+
+## Properties
+
+### path
+
+Underlying path polyfill
+
+```ts expandable
+path: path.Path;
+```
+
+### sep
+
+Separator used for joining path segments
+
+```ts expandable
+sep: string;
+```
+
+## Methods
+
+### basename()
+
+Return the last portion of path, since it is not a valid path, a string is returned.
+
+```ts expandable
+basename(filePath: IFilePath, suffix?: string): string;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+#### Example
+
+```ts
+const path = { filePath: "images/picture.png", storageUnit: ... };
+fpath.basename(path); // "picture.png"
+```
+
+<Separator />
+
+### concat()
+
+Concatenate fp with paths without adding separator
+
+```ts expandable
+concat(filePath: IFilePath, ...paths: string[]): IFilePath;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+#### Example
+
+```ts
+const path = { filePath: "uploads/archive.tar", storageUnit: ... };
+fpath.concat(path, "_extracted"); // { filePath: "uploads/archive.tar_extracted", storageUnit: ... }
+```
+
+<Separator />
+
+### dirname()
+
+Removes the last portion of path, returning the parent directory of the path. Ignores trailing slashes
+
+```ts expandable
+dirname(filePath: IFilePath): IFilePath;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+#### Example
+
+```ts
+const path = { filePath: "images/picture.png", storageUnit: ... };
+fpath.dirname(path); // { filePath: "images", storageUnit: ... }
+```
+
+<Separator />
+
+### extname()
+
+Returns extension of the path, from the last period, including the period.
+
+```ts expandable
+extname(filePath: IFilePath): string;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+#### Example
+
+```ts
+const path = { filePath: "images/picture.png", storageUnit: ... };
+fpath.dirname(path); // .png
+```
+
+<Separator />
+
+### isAbsolute()
+
+Always returns true, because all file paths are absolute
+
+```ts expandable
+isAbsolute(_: IFilePath): boolean;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+<Separator />
+
+### join()
+
+Returns new filePath with paths appended to it and normalized (resolved . and ..)
+
+```ts expandable
+join(filePath: IFilePath, ...paths: string[]): IFilePath;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+#### Example
+
+```ts
+const path = { filePath: "images", storageUnit: ... };
+fpath.join(path, "racoons", ".", "picture.png"); // { filePath: "images/racoons/picture.png", storageUnit: ... }
+```
+
+<Separator />
+
+### normalize()
+
+Resolves . and .. in the path and removes multiple slashes
+
+```ts expandable
+normalize(filePath: IFilePath): IFilePath;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+#### Example
+
+```ts
+const path = { filePath: "images//test/../test2/./", storageUnit: ... };
+fpath.normalize(path); // { filePath: "images/test2/", storageUnit: ... }
+```
+
+<Separator />
+
+### resolve()
+
+Same as fpath.join()
+
+```ts expandable
+resolve(filePath: IFilePath, ...paths: string[]): IFilePath;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+<Separator />
+
+### safeJoin()
+
+Similar to fpath.join, but resulting path will always be subdirectory of base
+
+```ts expandable
+safeJoin(base: IFilePath, ...paths: string[]): IFilePath;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+#### Example
+
+```ts
+const path = { filePath: "uploads/userA", storageUnit: ... };
+fpath.safeJoin(path, "..", "userB", "picture.png"); // { filePath: "uploads/userA/userB/picture.png", storageUnit: ... }
+```
+
+<Separator />
+
+### stringify()
+
+Convert filePath to string, this string is not guaranteed to be unique and should be only used for debugging/logging
+
+```ts expandable
+stringify(filePath: IFilePath): string;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```

package/docs/index.md

@@ -1,97 +1,30 @@
 ---
-title:  JS SDK Home
-author: Josef Kral
-date:   4.2.2018
-type:   rest-api
-tags:
-- rest_api
-- js_api
-- api
-description: "[Content JS API] General introduction to signageOS JS API"
+title: Introduction
+author: Alfonz Homolík
 ---
-# Javascript SDK for Applet development
 
-Javascript SDK gives you access to device's native features and functionalities. You can use the same functions across all devices with the same result.
+# Applet JS SDK
 
-:::tip
-All APIs are standardized and available across all [supported devices](https://docs.signageos.io/hc/en-us/sections/4405700629266-Supported-Devices).
-:::
+Applet JS SDK provides device's native features and functionalities with unified API for all supported platforms. This SDK is only usable
+inside of [signageOS applets](https://docs.signageos.io/hc/en-us/articles/4405068855570-Introduction-to-Applets) and allows you to create
+lightweight applets and deploy them on any device.
 
-:::info[Start here]
-[Basic information about Applets](applet-basics.md)
+```ts
+import sos from '@signageos/front-applet';
 
-General information required to use the signageOS JS API
-:::
+sos.onReady(async () => {
+	await sos.management.audio.setVolume(75);
+});
+```
 
-## Content-related JS APIs
+## Getting started
 
-Content-related APIs help you with content part of your application /Applet/. 
+The Getting started page summarizes key concept of applet development and will guide you through creating your first applet.
 
-Universal APIs for File system, access to accelerated video playback, sensor management and more provide you with robust tool set for creating extensive experiences.
+## Guides
 
-| Domain | Description |
-| ------ | ----------- |
-| [Applet Resources](content/js-applet-resources) | Pre-load necessary files required by your HTML5 player/Applet |
-| [Browser](content/js-browser) | Opening managed web-browser on Android devices inc. whitelisting, blacklisting and other features |
-| [Command](content/js-command) | Sending business or technical logs through signageOS in secured offline-ready way |
-| [Debug](content/js-debug) | Start debug session |
-| [Device Info](content/js-device-info) | Device-related informations  |
-| [Display](content/js-display) | Query features supported by the display |
-| [File system](content/js-file-system) | Full-featured file system API including ZIP and folder management |
-| [Fonts](content/js-fonts) | Make it easy to load additional fonts into SoC devices |
-| [Hardware](content/js-hardware) | Hardware-specific APIs like LED lights on Philips 10BDL |
-| [Inputs](content/js-input) | Controller inputs like IR remote unified under one API |
-| [iFrames](content/js-iframes) | Using JS SDK in iFrames |
-| [Proof of Play](content/js-proof-of-play) | Proof of Play API |
-| [Sensors](content/js-sensors) | Using sensors and IoT devices in your application  |
-| [Serial Port](content/js-serial) | Control external devices via serial |
-| [Synchronized playback](content/js-sync-playback) | API for creating synced playback and videowalls  |
-| [Video Inputs aka PiP](content/js-video-inputs-internal-ports) | Show HDMI/DP/VGA as a part of your content via PiP feature |
-| [Video Playback](content/js-video) | Playing accelerated gapless videos via native video player |
-| [Video Streams](content/js-video-stream) | Playing video streams (RTSP, HLS, UDP) via native video player  
+In Guides section contains articles which describe how to use the SDK with explanation and examples.
 
-## Device control JS APIs
+## API Reference
 
-Device control features exposed via Javascript APIs.
-
-:::tip
-For **Device Management** we strongly recommend using REST APIs. [See the REST API documentation here](https://developers.signageos.io/api/).
-:::
-
-
-| Domain | Description |
-| ------ | ----------- |
-| [Application](management/js-management-application) | Get application version and upgrade application from remote location |
-| [Audio](management/js-management-audio) | Control system volume level |
-| [Debug](management/js-management-debug) | Enable/disable debug mode |
-| [Firmware](management/js-management-firmware) | Get FW version and upgrade FW from remote location |
-| [Management](management/js-management-management) | Information about the device and power action like Reboot, Restart,.. |
-| [Monitors](management/js-management-monitors) | Information about monitors |
-| [Network](management/js-management-network) | Manage network settings |
-| [OS](management/js-management-os) | Get system information like CPU and Memory usage |
-| [Package](management/js-management-package) | Install and manage packages |
-| [Power](management/js-management-power) | Manage display power - timers, restart and reboot |
-| [Proxy](management/js-management-proxy) | Manage display network proxy setup |
-| [IR Remote Control](management/js-management-remote-control) | Manage IR Remote control functionality |
-| [Screen](management/js-management-screen) | Manage brightness, orientation and resolution, display on/off |
-| [Security](management/js-management-security) | Control system security (PIN code) |
-| [Time](management/js-management-time) | Set time, timezone and get current settings |
-| [Wi-Fi](management/js-management-wifi) | Manage Wi-Fi 
-
-# Testing Framework SDK
-
-Write and then run **automated tests** for your applet on physical devices, streamlining your development and QA efforts.
-
-See full [documentation on GitHub](https://github.com/signageos/test-framework)
-
-# Node.JS SDK
-
-Library which allows you to fully manage signageOS applets, devices, management & monitoring using Node.JS and REST API.
-
-See full [documentation on GitHub](https://github.com/signageos/sdk)
-
-# REST API
-
-Large collection of REST API endpoints for device management and monitoring.
-
-See full [documentation on Postman](https://developers.signageos.io/api/)
+Our API reference offers a complete list of APIs in the SDK with a description what it does and what is possible with it.

package/docs/sos/browser.md

@@ -0,0 +1,210 @@
+# browser
+
+The `sos.browser` API groups together methods for working with the integrated web browser.
+
+:::info
+
+**This API is currently available on:**
+- Android devices with Android 5+ (Philips, Benq, Sharp, generic Android device)
+
+**With some limitation you can use this API also on**
+- Samsung Tizen (SSSP 4 and above); where the website is just in fullscreen without an address bar or theme options (headless mode)
+- LG webOS (webOS 3.0 and above); where the website is just in fullscreen without an address bar or theme options (headless mode)
+- Linux (Fedora, Ubuntu), Raspberry Pi, NEC Compute Module; where the website is just in fullscreen without an address bar or theme options (headless mode)
+- BrightSign; where the website is just in fullscreen without an address bar or theme options (headless mode)
+
+:::
+
+## Methods
+
+### close()
+
+The `close()` method closes the browser window opened by the `open()` method.
+
+```ts expandable
+close(): Promise<void>;
+```
+
+<Separator />
+
+### onClose()
+
+The `onClose()` method sets up a listener, which is called whenever a browser window is closed. This can happen by an API call, by a
+user request or after a timeout. This doesn't fire between `open` calls or on subsequent `close` calls.
+
+```ts expandable
+onClose(listener: (event: CloseEvent) => void): () => void;
+// show-more
+interface CloseEvent extends Event<EventType.CLOSE> {
+    reason: CloseReason;
+}
+
+enum EventType {
+    CLOSE = "close"
+}
+
+enum CloseReason {
+    API = "API",
+    USER = "USER",
+    TIMEOUT = "TIMEOUT"
+}
+
+type Event<TType extends EventType = EventType> = {
+    type: TType;
+};
+
+```
+
+#### Return value
+
+A callback which removes the listener.
+
+<Separator />
+
+### open()
+
+The `open()` method opens the specified url in a browser window.
+
+```ts expandable
+open(uri: string, options?: IOpenLinkOptions): Promise<void>;
+// show-more
+interface IOpenLinkOptions {
+    aclDomains?: string[];
+    aclMode?: 'blacklist' | 'whitelist';
+    readOnlyAddressBar?: boolean;
+    idleTimeout?: number;
+    coordinates?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    theme?: ITheme;
+    headlessMode?: boolean;
+    clearData?: boolean;
+    canUserClose?: boolean;
+    method?: 'native' | 'iframe';
+}
+
+type ITheme = {
+    base?: 'light' | 'dark';
+    shape?: {
+        cornerSize?: number;
+    };
+    colors?: {
+        primary?: Color;
+        background?: Color;
+        control?: Color;
+    };
+    widgets?: {
+        editAddress?: {
+            colors?: {
+                background?: Color;
+                text?: Color;
+            };
+        };
+        buttonClose?: {
+            colors?: {
+                background?: Color | '@primary';
+                text?: Color;
+                icon?: Color;
+            };
+            icon?: 'none' | 'exit_to_app' | 'close' | 'cancel';
+            text?: string;
+        };
+        progress?: {
+            color?: Color | '@primary';
+        };
+    };
+};
+
+```
+
+#### Params
+
+| Name                                      | Type                                                       | Description                                                                             |
+|-------------------------------------------|------------------------------------------------------------|-----------------------------------------------------------------------------------------|
+| `options.aclDomains` *(optional)*         | `string[]`                                                 | List of domains to be interpreted according to `aclMode`.                               |
+| `options.aclMode` *(optional)*            | `"blacklist" \| "whitelist"`                               | Either "blacklist" or "whitelist".                                                      |
+| `options.readOnlyAddressBar` *(optional)* | `boolean`                                                  | Should the address bar be readonly.                                                     |
+| `options.idleTimeout` *(optional)*        | `number`                                                   | Close browser after specified period if idle.                                           |
+| `options.coordinates` *(optional)*        | `{ x: number; y: number; width: number; height: number; }` | Size and position of the browser window. Defaults to fullscreen.                        |
+| `options.theme` *(optional)*              | `ITheme`                                                   | Specify custom UI theme. (Android only)                                                 |
+| `options.headlessMode` *(optional)*       | `boolean`                                                  | Headless mode hides the entire address bar. (Android only)                              |
+| `options.canUserClose` *(optional)*       | `boolean`                                                  | Whether the user can manually close the browser. (default if headless false, else true) |
+| `options.clearData` *(optional)*          | `boolean`                                                  | Clear cache after the browser closes. (default if headless false, else true)            |
+| `options.method` *(optional)*             | `"native" \| "iframe"`                                     | Either "native" or "iframe"                                                             |
+
+#### Example
+
+```ts
+sos.browser.open('https://www.signageos.io', {
+	aclDomains: ['google.com', 'yahoo.com'],
+	aclMode: 'blacklist', // or 'whitelist'
+	readOnlyAddressBar: true,
+	coordinates: { // Supported only on Linux and Android
+		x: 0,
+		y: 0,
+		height: 500,
+		width: 500,
+	},
+	// theme: { ... }
+	headlessMode: false,
+});
+```
+
+<Separator />
+
+### ~openLink()~
+
+:::danger
+
+This method was deprecated. use `sos.browser.open()` instead
+
+:::
+
+```ts expandable
+openLink(uri: string, options?: IDeprecatedOpenLinkOptions): Promise<void>;
+// show-more
+/** @deprecated */
+interface IDeprecatedOpenLinkOptions {
+    acl?: RegExp[];
+    aclMode?: 'blacklist' | 'whitelist';
+    readOnlyAddressBar?: boolean;
+    idleTimeout?: number;
+    theme?: ITheme;
+}
+
+type ITheme = {
+    base?: 'light' | 'dark';
+    shape?: {
+        cornerSize?: number;
+    };
+    colors?: {
+        primary?: Color;
+        background?: Color;
+        control?: Color;
+    };
+    widgets?: {
+        editAddress?: {
+            colors?: {
+                background?: Color;
+                text?: Color;
+            };
+        };
+        buttonClose?: {
+            colors?: {
+                background?: Color | '@primary';
+                text?: Color;
+                icon?: Color;
+            };
+            icon?: 'none' | 'exit_to_app' | 'close' | 'cancel';
+            text?: string;
+        };
+        progress?: {
+            color?: Color | '@primary';
+        };
+    };
+};
+
+```

package/docs/sos/command.md

@@ -0,0 +1,68 @@
+# command
+
+The `sos.command` API groups together methods for sending logs and receiving commands from signageOS.
+
+## Methods
+
+### dispatch()
+
+The `dispatch()` method dispatches a new log record to the signageOS.
+
+:::warning[Dispatch throttling]
+
+Sending commands from an applet is throttled, this means that after if the dispatch frequency is too high, some commands may be
+discarded. Currently the limit is 30 commands per 30 seconds, although this may not be fully accurate and it's not possible to know the
+exact limit.
+
+:::
+
+```ts expandable
+dispatch<TCommand extends ICommand>(command: TCommand): Promise<void>;
+// show-more
+interface ICommand {
+    type: string;
+}
+
+```
+
+#### Example
+
+```ts
+await sos.command.dispatch({
+  type: 'Files.StartLoading',
+  fileName: 'my-file',
+  fileType: 'txt'
+});
+```
+
+:::note[GitHub Example]
+
+- [Sending commands](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/command/sending/)
+
+:::
+
+<Separator />
+
+### onCommand()
+
+The `onCommand()` method sets up a listener, which is called whenever a new command from signageOS is received.
+
+```ts expandable
+onCommand(listener: (command: ICommandEvent) => void): void;
+// show-more
+interface ICommandEvent {
+    type: 'command';
+    command: ICommand;
+}
+
+interface ICommand {
+    type: string;
+}
+
+```
+
+:::note[GitHub Example]
+
+- [Receiving commands](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/command/receiving)
+
+:::