@signageos/front-applet 8.2.0 → 8.2.2

package/docs/index.md

@@ -6,11 +6,11 @@ sidebar_position: 0
 
 # Applet JS SDK
 
-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
+Applet JS SDK provides the device's native features and functionalities with a unified API for all supported platforms. This SDK is only usable
+inside [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.
 
-```ts
+```ts title="Simple example of Applet
 import sos from '@signageos/front-applet';
 
 sos.onReady(async () => {
@@ -19,13 +19,13 @@ sos.onReady(async () => {
 ```
 
 ## Getting started
+This section refers to the JS SDK API reference and provides detailed information for every function, including rich examples.
 
-The Getting started page summarizes key concept of applet development and will guide you through creating your first applet.
-
-## Guides
-
-In Guides section contains articles which describe how to use the SDK with explanation and examples.
+To develop an applet using the Applet JS SDK, you need to install our [CLI](https://developers.signageos.io/docs/cli-setup) and follow our guide [Getting started with Applets](https://developers-staging.signageos.io/docs/applets/getting-started/).
 
 ## API Reference
+The JS API reference is divided into two main sections:
+- `sos` - Main object which contains APIs for controlling video playback, streams, or serial ports.
+- `sos.management` - This section contains management APIs for controlling the device's features like audio, network, Wi-Fi, etc.
 
-Our API reference offers a complete list of APIs in the SDK with a description what it does and what is possible with it.
+You can also check our public examples on [GitHub](https://github.com/signageos/applet-examples/)

package/docs/sos/browser.md

@@ -4,21 +4,29 @@ sidebar_position: 0
 
 # browser
 
-There are several use-cases when you need to open a web browser on a touch-enabled device (also known as a tablet). For these cases, you can use a custom web browser we built. Default URL can be opened and even the whitelisting/blacklisting of certain domains is supported.
+There are several use cases when you need to open a web browser on a touch-enabled device (also known as a tablet). For these cases, you can use a custom web browser we built. Default URL can be opened and even the whitelisting/blacklisting of certain domains is supported.
 
 :::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**
+**With some limitations, you can also use this API 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)
-
 :::
 
+<details>
+    <summary>Device Browser Capabilities</summary>
+		| Capability | Description |
+		|:------------|:-------------|
+		| `BROWSER` | If device can open browser with custom URL |
+
+		If you want to check if the device supports this capability, use [`sos.display.supports()`](https://developers.signageos.io/sdk/sos/display#supports).
+</details>
+
 ## Methods
 
 ### close()

package/docs/sos/deviceInfo.md

@@ -19,7 +19,7 @@ Device name can be set only in CloudControl on Device Info page, or via [Rest AP
 :::
 
 ```ts expandable
-getDeviceName(): Promise<string>;
+getDeviceName(): Promise<string | null>;
 ```
 
 #### Return value

package/docs/sos/display.md

@@ -7,30 +7,23 @@ sidebar_position: 0
 The `sos.display` API groups together methods for getting information about the device. Primarily to find out which
 features it supports.
 
-<details>
-    <summary>List of all display capabilities</summary>
-		| Capability | Description |
-		|:------------|:-------------|
-		| `FILE_SYSTEM_INTERNAL_STORAGE` | If device supports internal storage |
-		| `FILE_SYSTEM_EXTERNAL_STORAGE` | If device supports external storage |
-		| `FILE_SYSTEM_FILE_CHECKSUM` | If device supports file checksum calculation |
-		| `FILE_SYSTEM_LINK` | If device supports file system `link()` |
-		| `FILE_SYSTEM_CREATE_ARCHIVE` | If device supports creating archives in the file system |
-		| `FILE_SYSTEM_ARCHIVE_EXTRACT_INFO` | If device can determine a total size of a potentially extracted archive |
-		| `TIMERS_PROPRIETARY` | If device supports proprietary timers |
-		| `VIDEO_4K` | If device supports 4K video playback |
-		| `BROWSER` | If device supports opening browser |
-		| `SERIAL` | If device supports serial port communication |
-		| `BARCODE_SCANNER` | If device supports barcode scanner setup |
-		| `FRONT_OSD` | If device supports Front OSD (our on-screen display) |
-		| `PROXIMITY_SENSOR` | If device supports proximity sensor |
-</details>
-
 ## Methods
 
 ### supports()
 
-The `supports()` method determines whether a queried capability is supported by the device.
+The `supports()` method determines whether the device supports a queried capability.
+
+#### What are capabilities?
+Capabilities are features or functionalities that a device can support. We divided those capabilities into `front` and `management` capabilities.
+This section is about front capabilities, which include features like handling serial ports, video and stream playback, and more.
+
+On the other hand, the `management` capabilities are features that are related to the application management, such as app upgrade, app version, and more.
+To check `management` capabilities, refer to the `sos.management.supports()` method or [this section](https://developers.signageos.io/sdk/sos_management/#supports).
+
+:::tip
+If you want to check specific capabilities, refer to the sidebar for the selected management section. Every section has its capabilities written in the description,
+or check the **DisplayCapability** type in `supports()` methods. It has a list of all available capabilities for all platforms.
+:::
 
 ```ts expandable
 supports(capability: DisplayCapability): Promise<boolean>;

package/docs/sos/fileSystem.md

@@ -17,6 +17,20 @@ Applet Reload only deletes `/data` directory which is reserved for simplified [O
 - [Example usage of File System API in Applet](https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/file-system)
 :::
 
+<details>
+    <summary>Device File System Capabilities</summary>
+		| Capability | Description |
+		|:------------|:-------------|
+		| `FILE_SYSTEM_INTERNAL_STORAGE` | If device supports internal storage units |
+	 	| `FILE_SYSTEM_EXTERNAL_STORAGE` | If device supports connecting external storage units |
+		| `FILE_SYSTEM_FILE_CHECKSUM` | If device supports checksum for MD5 or CRC32 hash algorithms |
+		| `FILE_SYSTEM_LINK` | If device supports creating hard links to files |
+		| `FILE_SYSTEM_CREATE_ARCHIVE` | If device supports creating archives - zip |
+		| `FILE_SYSTEM_ARCHIVE_EXTRACT_INFO` | If device supports extracting information about archive files |
+
+		If you want to check if the device supports this capability, use [`sos.display.supports()`](https://developers.signageos.io/sdk/sos/display#supports).
+</details>
+
 
 ## Storing files permanently
 To allow more low-level file operations, the applet SDK exposes the File System API. Files created using this API are permanent and are only removed on a factory reset or file system wipeout.
@@ -1261,7 +1275,7 @@ files.forEach((file) => {
 
 ### listInternalStorageUnits()
 
-A shorthand method for listing only the internal storage units (i.e. those with the `removable: false`). The capacity values are in bytes.
+A shorthand method for listing only the internal storage units (i.e., those with the `removable: false`). The capacity values are in bytes.
 
 ```ts expandable
 listInternalStorageUnits(): Promise<IStorageUnit[]>;
@@ -1596,7 +1610,12 @@ removeStorageUnitsChangedListener(listener: () => void): void;
 
 ### wipeout()
 
-The `wipeout()` method is used to wipe out all data from the file system, later when action is finished the device is rebooted.
+The `wipeout()` method is used to wipe out all data from the file system.
+
+:::danger
+- Ensure that function is called only once, otherwise it will wipe out the file system again on applet or device start!
+- This function is clearing internal file system storage, cache storage and cookies. Local storage will not be cleared.
+:::
 
 ```ts expandable
 wipeout(): Promise<void>;
@@ -1606,10 +1625,16 @@ wipeout(): Promise<void>;
 
 A promise that resolves when the wipeout is complete.
 
-:::danger
-- Ensure that function is called only once, otherwise it will wipe out the file system again on applet start!
-- This function is clearing internal file system storage, cache storage and cookies. Local storage will not be cleared.
-:::
+#### Example
+
+```ts
+await sos.fileSystem.wipeout().then(() => {
+	console.log('File system wiped out successfully.');
+	await sos.management.power.systemReboot(); // Reboot the device after wipeout
+}).catch((error) => {
+	console.error('Error wiping out file system:', error);
+});
+```
 
 <Separator />
 

package/docs/sos/hardware/barcodeScanner.md

@@ -11,6 +11,15 @@ It allows starting and stopping the scanner, as well as listening for scanned da
 This API is experimental and may change in the future.
 :::
 
+<details>
+    <summary>Device Barcode Scanner Capabilities</summary>
+		| Capability | Description |
+		|:------------|:-------------|
+		| `BARCODE_SCANNER` | If device supports serial communication for Barcode Scanners |
+
+		If you want to check if the device supports this capability, use [`sos.display.supports()`](https://developers.signageos.io/sdk/sos/display#supports).
+</details>
+
 ## Methods
 
 ### getVersion()

package/docs/sos/hardware/index.md

@@ -11,6 +11,15 @@ The `sos.hardware` API groups together methods for working with hardware. It all
 - Samsung Kiosk serial connection only works over serial ports, not over USB ports.
 :::
 
+<details>
+    <summary>Device Hardware Capabilities</summary>
+		| Capability | Description |
+		|:------------|:-------------|
+		| `SERIAL` | If the device supports sending and receiving data via serial ports |
+
+		If you want to check if the device supports this capability, use [`sos.display.supports()`](https://developers.signageos.io/sdk/sos/display#supports).
+</details>
+
 ### List of supported serial ports
 Bellow is example list of serial ports that can be used with `sos.hardware.openSerialPort()` method.
 

package/docs/sos/native/mdc.md

@@ -10,9 +10,14 @@ The `sos.native.mdc` API groups together methods for controlling Tizen devices u
 This API is currently available on Tizen devices only.
 :::
 
-:::info
-You can ensure that the device supports MDC commands via `sos.management.supports("NATIVE_COMMANDS_MDC")`.
-:::
+<details>
+    <summary>MDC Management Capabilities</summary>
+		| Capability | Description |
+		|:------------|:-------------|
+		| `NATIVE_COMMANDS_MDC` | If device supports performing MDC commands |
+
+		If you want to check if the device supports this capability, use [`sos.management.supports()`](https://developers.signageos.io/sdk/sos_management/#supports).
+</details>
 
 ## Methods
 

package/docs/sos/osd.md

@@ -8,6 +8,15 @@ The `sos.osd` API groups together methods for working with the signageOS OSD (On
 
 More information about the OSD can be found in the [OSD Introduction](https://docs.signageos.io/hc/en-us/articles/4405231839890-OSD-menu-by-signageOS)
 
+<details>
+    <summary>Front OSD Capabilities</summary>
+		| Capability | Description |
+		|:------------|:-------------|
+		| `FRONT_OSD` | If device supports opening OSD |
+
+		If you want to check if the device supports this capability, use [`sos.display.supports()`](https://developers.signageos.io/sdk/sos/display#supports).
+</details>
+
 ## Methods
 
 ### showOSD()

package/docs/sos/video.md

@@ -16,6 +16,15 @@ The `sos.video` provides you 4 methods to handle the playback:
 First 5 parameters (uri, x, y, width, and height) are unique identifiers for playing the video using play, stop, resume, and pause methods.
 :::
 
+<details>
+    <summary>Device Video Capabilities</summary>
+		| Capability | Description |
+		|:------------|:-------------|
+		| `VIDEO_4K` | If device supports playing 4k videos |
+
+		If you want to check if the device supports this capability, use [`sos.display.supports()`](https://developers.signageos.io/sdk/sos/display#supports).
+</details>
+
 ## Gapless video playback
 It is often desirable to be able to play different videos consecutively without "black" frames. To achieve this next video in the queue needs to be loaded before the current video ends. How to achieve this may differ from platform to platform. Applet JS SDK handles this under the hood and provides you with `prepare()`, `play()` and `stop()` methods.
 Each video has to be pre-loaded with `prepare()` while the previous video is still playing, and after the video ends it should be unloaded immediately with `stop()`. This is because some (especially older ones) platforms support that only 2 videos are loaded into memory at any time (one playing and one ready to play).

package/docs/sos_management/app.md

@@ -6,49 +6,76 @@ sidebar_position: 0
 
 The `sos.management.app` API groups together methods for managing the signageOS application installed on the system.
 
+<details>
+    <summary>App Management Capabilities</summary>
+		| Capability | Description |
+		|:------------|:-------------|
+		| `APP_UPGRADE` | If the signageOS application can upgrade itself to a specific version |
+
+		If you want to check if the device supports this capability, use [`sos.management.supports()`](https://developers.signageos.io/sdk/sos_management/#supports).
+</details>
+
 ## Methods
 
 ### getType()
 
-The `getType()` method returns type of the platform the application is running on.
+The `getType()` method returns the type of the platform the application is running on.
 
 :::info
-
-If you need to get specific Android brand or Raspberry Pi model, use the `sos.management.firmware.getType()`.
-
+- If you need to get a specific Android brand or Raspberry Pi model, use the `sos.management.firmware.getType()`.
+- `default` type is always Emulator.
 :::
 
 ```ts expandable
 getType(): Promise<AppType>;
 // show-more
+/**
+ * All available app types
+ */
 type AppType = 'android' | 'brightsign' | 'default' | 'linux' | 'sssp' | 'tizen' | 'webos' | 'windows' | 'chromeos' | AnyString;
 
 type AnyString = string & {};
 
 ```
 
-<Separator />
+#### Return value
 
-### getVersion()
+Resolves to the type of the application platform.
 
-The `getVersion()` method returns version of the application currently running.
+#### Example
 
-:::info
+```ts
+const appType = await sos.management.app.getType();
+console.log(appType); // tizen, linux, webos, etc.
+```
 
-This API is only available for Applets deployed via Timing from Box or REST API.
+<Separator />
 
-:::
+### getVersion()
+
+The `getVersion()` method returns the version of the Core App that is currently running on the device.
 
 ```ts expandable
 getVersion(): Promise<string>;
 ```
 
+#### Return value
+
+Resolves to the version of the Core application.
+
+#### Example
+
+```ts
+const version = await sos.management.app.getVersion();
+console.log(`Current application version is: ${version}`); // e.g. '4.0.0', '5.2.1', etc.
+```
+
 <Separator />
 
 ### upgrade(appUri)
 
-The `upgrade(appUri)` method upgrades the signageOS application with provided appUri. Open users can upgrade app passing FQN
-uri where the application main file is located.
+The `upgrade(appUri)` method upgrades the signageOS application with the provided `appUri`. Open users can upgrade the app passing FQN
+URI where the application's main file is located.
 
 This file type/extension differs for every platform. E.g.:
 - SSSP: http://example.com/apps/sssp_config.xml or http://example.com/apps/ApplicationName.zip
@@ -58,6 +85,11 @@ This file type/extension differs for every platform. E.g.:
 - Brightsign: http://example.com/apps/ApplicationName.zip
 - Linux: http://example.com/apps/ApplicationName.apk
 - Android: http://example.com/apps/ApplicationName.apk
+- ChromeOS: Not supported
+
+:::tip
+Check our latest versions in our [changelogs](https://docs.signageos.io/hc/en-us/sections/4409161443730-Core-Apps).
+:::
 
 ```ts expandable
 upgrade(appUri: string): Promise<void>;
@@ -65,9 +97,36 @@ upgrade(appUri: string): Promise<void>;
 
 #### Params
 
-| Name     | Type     | Required         | Description                                         |
-|----------|----------|------------------|-----------------------------------------------------|
-| `appUri` | `string` |  <div>Yes</div>  | FQN uri where the application main file is located. |
+| Name     | Type     | Required         | Description                                           |
+|----------|----------|------------------|-------------------------------------------------------|
+| `appUri` | `string` |  <div>Yes</div>  | FQN uri where the application's main file is located. |
+
+#### Return value
+
+A promise that resolves when the upgrade starts.
+
+#### Possible errors
+
+If the upgrade fails.
+
+#### Example
+
+```ts
+// Upgrade the application to a specific version
+await sos.management.app.upgrade('http://example.com/apps/ApplicationName.zip')
+ .then(() => {
+		console.log('Application upgrade started successfully.');
+ })
+ .catch((error) => {
+		console.error('Failed to start application upgrade:', error);
+ });
+```
+
+:::note[GitHub Example]
+
+- [ How to upgrade application via applets](https://github.com/signageos/applet-examples/tree/master/examples/management-js-api/app-upgrade)
+
+:::
 
 <Separator />
 
@@ -90,8 +149,8 @@ upgrade(baseUrl: string, version: string): Promise<void>;
 
 ### upgrade(version, baseUrl)
 
-The `upgrade(version, baseUrl?)` method upgrades the signageOS application using version and baseUrl. Platform users can install general
-application version directly with passing just version number. Optionally, the baseUrl can be passed as argument to specify server
+The `upgrade(version, baseUrl?)` method upgrades the signageOS application using version and baseUrl. Platform users can install the general
+application version directly with passing just the version number. Optionally, the baseUrl can be passed as an argument to specify the server
 where the application files are accessible.
 
 ```ts expandable
@@ -103,4 +162,24 @@ upgrade(version: string, baseUrl?: string): Promise<void>;
 | Name      | Type     | Required         | Description                                                                                              |
 |-----------|----------|------------------|----------------------------------------------------------------------------------------------------------|
 | `version` | `string` |  <div>Yes</div>  | The version of the application being installed.                                                          |
-| `baseUrl` | `string` |  <div>No</div>   | Optional server URL where application files are located.<br/>(Default value: `"https://2.signageos.io"`) |
+| `baseUrl` | `string` |  <div>No</div>   | Optional server URL where application files are located.<br/>(Default value: `"https://2.signageos.io"`) |
+
+#### Return value
+
+A promise that resolves when the upgrade starts.
+
+#### Possible errors
+
+If the upgrade fails.
+
+#### Example
+
+```ts
+await sos.management.app.upgrade('4.0.0', 'https://2.signageos.io')
+```
+
+:::note[GitHub Example]
+
+- [ How to upgrade application via applets](https://github.com/signageos/applet-examples/tree/master/examples/management-js-api/app-upgrade)
+
+:::

package/docs/sos_management/audio.md

@@ -6,21 +6,42 @@ sidebar_position: 0
 
 The `sos.management.audio` API groups methods for managing audio settings.
 
+<details>
+    <summary>Volume Management Capabilities</summary>
+		| Capability | Description |
+		|:------------|:-------------|
+		| `SET_VOLUME` | If device can set volume level |
+		| `GET_VOLUME` | If device can get current volume level |
+
+		If you want to check if the device supports those capabilities, use [`sos.management.supports()`](https://developers.signageos.io/sdk/sos_management/#supports).
+</details>
+
 ## Methods
 
 ### getVolume()
 
-The `getVolume()` method returns current volume level of the device.
+The `getVolume()` method returns the current volume level of the device.
 
 ```ts expandable
 getVolume(): Promise<number>;
 ```
 
+#### Return value
+
+A promise that resolves to the current volume level, which is a value between 0 and 100.
+
+#### Example
+
+```ts
+const currentVolume = await sos.management.audio.getVolume();
+console.log(`Current volume level is: ${currentVolume}`); // e.g. 75
+```
+
 <Separator />
 
 ### setVolume()
 
-The `getVolume()` method set the volume level of the device.
+The `setVolume()` method sets the volume level of the device.
 
 ```ts expandable
 setVolume(volume: number): Promise<void>;
@@ -32,6 +53,26 @@ setVolume(volume: number): Promise<void>;
 |----------|----------|------------------|--------------------------|
 | `volume` | `number` |  <div>Yes</div>  | Value between 0 and 100. |
 
+#### Return value
+
+A promise that resolves when the volume is set.
+
+#### Possible errors
+
+If the volume is not a number or is outside the range of 0 to 100.
+
+#### Example
+
+```ts
+await sos.management.audio.setVolume(50);
+```
+
+:::note[GitHub Example]
+
+- [ Example applet with setting volume](https://github.com/signageos/applet-examples/tree/master/examples/management-js-api/volume)
+
+:::
+
 ## API Example
 
 ```ts

package/docs/sos_management/autoRecovery.md

@@ -0,0 +1,101 @@
+---
+sidebar_position: 0
+---
+
+# autoRecovery
+
+The `sos.management.autoRecovery` API provides methods for managing the auto-recovery feature of the signageOS app.
+
+The Auto Recovery feature is designed to automatically recover the signageOS app in case of a crash or unexpected shutdown
+or switching input to a different value, e.g., HDMI.
+
+<details>
+    <summary>Auto Recovery Management Capabilities</summary>
+		| Capability | Description |
+		|:------------|:-------------|
+		| `AUTO_RECOVERY` | If the device can enable or disable the auto recovery function. |
+
+		If you want to check if the device supports this capability, use [`sos.management.supports()`](https://developers.signageos.io/sdk/sos_management/#supports).
+</details>
+
+## Methods
+
+### get()
+
+The `get()` method retrieves the current auto-recovery configuration.
+
+```ts expandable
+get(): Promise<IAutoRecoveryConfiguration>;
+// show-more
+type IAutoRecoveryConfiguration = {
+    enabled: false;
+    autoEnableTimeoutMs?: number;
+} | {
+    enabled: true;
+    healthcheckIntervalMs: number;
+};
+
+```
+
+#### Return value
+
+A promise that resolves to the current auto-recovery configuration.
+
+#### Example
+
+```ts
+const autoRecoveryConfig = await sos.management.autoRecovery.get();
+if (autoRecoveryConfig.enabled) {
+  console.log(`Auto-recovery is enabled with a healthcheck interval of ${autoRecoveryConfig.healthcheckIntervalMs} ms.`);
+}
+```
+
+<Separator />
+
+### set()
+
+The `set()` method allows to enable or disable the auto-recovery feature and configure its settings.
+
+:::note
+The configuration object has different properties depending on if enabled is true or false.
+:::
+
+```ts expandable
+set(configuration: IAutoRecoveryConfiguration): Promise<void>;
+// show-more
+type IAutoRecoveryConfiguration = {
+    enabled: false;
+    autoEnableTimeoutMs?: number;
+} | {
+    enabled: true;
+    healthcheckIntervalMs: number;
+};
+
+```
+
+#### Params
+
+| Name                                  | Type                         | Required         | Description                                                                                                 |
+|---------------------------------------|------------------------------|------------------|-------------------------------------------------------------------------------------------------------------|
+| `configuration`                       | `IAutoRecoveryConfiguration` |  <div>Yes</div>  | The configuration object for auto-recovery settings.                                                        |
+| `configuration.enabled`               | `true`                       |  <div>Yes</div>  | A boolean to set auto-recovery to enabled or disabled state.                                                |
+| `configuration.autoEnableTimeoutMs`   | `number`                     |  <div>No</div>   | The timeout in milliseconds after which the auto-recovery will be automatically enabled if it was disabled. |
+| `configuration.healthcheckIntervalMs` | `number`                     |  <div>Yes</div>  | The interval in milliseconds for the health check if application is running in foreground.                  |
+
+#### Return value
+
+A promise that resolves when the auto-recovery settings are successfully set.
+
+#### Possible errors
+
+If the configuration is invalid.
+
+#### Example
+
+```ts
+// Enable auto-recovery with a healthcheck interval of 5000 ms
+await sos.management.autoRecovery.set({
+	enabled: true,
+	healthcheckIntervalMs: 5000,
+});
+```