@signageos/front-applet 8.1.1 → 8.1.3

package/docs/sos/browser.md

@@ -4,7 +4,7 @@ sidebar_position: 0
 
 # browser
 
-The `sos.browser` API groups together methods for working with the integrated web 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.
 
 :::info
 
@@ -29,6 +29,20 @@ The `close()` method closes the browser window opened by the `open()` method.
 close(): Promise<void>;
 ```
 
+#### Return value
+
+A promise that resolves when the browser is closed.
+
+#### Example
+
+```ts
+await sos.browser.open('https://www.signageos.io', {
+	readOnlyAddressBar: true,
+});
+// some time later
+await sos.browser.close();
+```
+
 <Separator />
 
 ### onClose()
@@ -39,7 +53,13 @@ user request or after a timeout. This doesn't fire between `open` calls or on su
 ```ts expandable
 onClose(listener: (event: CloseEvent) => void): () => void;
 // show-more
+/**
+ * Interface representing a close event in the browser.
+ */
 interface CloseEvent extends Event<EventType.CLOSE> {
+    /**
+     * The reason for the browser being closed.
+     */
     reason: CloseReason;
 }
 
@@ -59,6 +79,12 @@ type Event<TType extends EventType = EventType> = {
 
 ```
 
+#### Params
+
+| Name       | Type                          | Description                                           |
+|------------|-------------------------------|-------------------------------------------------------|
+| `listener` | `(event: CloseEvent) => void` | The listener to be called when the browser is closed. |
+
 #### Return value
 
 A callback which removes the listener.
@@ -72,6 +98,9 @@ The `open()` method opens the specified url in a browser window.
 ```ts expandable
 open(uri: string, options?: IOpenLinkOptions): Promise<void>;
 // show-more
+/**
+ * Interface defines the options for opening a link in the browser.
+ */
 interface IOpenLinkOptions {
     aclDomains?: string[];
     aclMode?: 'blacklist' | 'whitelist';
@@ -87,6 +116,10 @@ interface IOpenLinkOptions {
     headlessMode?: boolean;
     clearData?: boolean;
     canUserClose?: boolean;
+    /**
+     * Method of opening the link.
+     * @default 'native'
+     */
     method?: 'native' | 'iframe';
 }
 
@@ -126,23 +159,36 @@ type ITheme = {
 
 #### 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"                                                             |
+| Name                                      | Type                                                       | Description                                                                                                                                                               |
+|-------------------------------------------|------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `uri`                                     | `string`                                                   | The URL to open in the browser.                                                                                                                                           |
+| `options` *(optional)*                    | `IOpenLinkOptions`                                         | Optional parameters to configure the browser window.                                                                                                                      |
+| `options.aclDomains` *(optional)*         | `string[]`                                                 | List of domains to be interpreted according to `aclMode`. Example: `signageos.io`, `www.example.com`                                                                      |
+| `options.aclMode` *(optional)*            | `"blacklist" \| "whitelist"`                               | `blacklist` – Allow access to all domains except those in aclDomains and their subdomains, `whitelist` – Allow access only to domains in aclDomains and their subdomains. |
+| `options.readOnlyAddressBar` *(optional)* | `boolean`                                                  | If `true`, the address bar is read-only, if `false` the user can navigate away by entering a URL in the address bar.                                                      |
+| `options.idleTimeout` *(optional)*        | `number`                                                   | The browser will automatically close after a specified period of inactivity (in milliseconds).                                                                            |
+| `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"`                                     | Can only be native (which opens a new, fully sandboxed fullscreen window) or iframe (which opens a configurable-sized window). (only Linux)                               |
+
+#### Return value
+
+A promise that resolves when the browser is opened.
+
+#### Possible errors
+
+
+- If the `uri` is not a valid URL or string.
+- If the `options` are not valid.
+- If unexpected error occurred when opening link.
 
 #### Example
 
 ```ts
-sos.browser.open('https://www.signageos.io', {
+await sos.browser.open('https://www.signageos.io', {
 	aclDomains: ['google.com', 'yahoo.com'],
 	aclMode: 'blacklist', // or 'whitelist'
 	readOnlyAddressBar: true,
@@ -157,6 +203,12 @@ sos.browser.open('https://www.signageos.io', {
 });
 ```
 
+:::note[GitHub Example]
+
+- [ Example of Applet for using browser on Android ](https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/browser)
+
+:::
+
 <Separator />
 
 ### ~openLink()~

package/docs/sos/command.md

@@ -4,7 +4,9 @@ sidebar_position: 0
 
 # command
 
-The `sos.command` API groups together methods for sending logs and receiving commands from signageOS.
+In some cases, you might be interested in a complete log of what the device was doing during its operation. All of your business or technical logs can be stored in our storage for later usage. You can identify which events happened or even trigger self-repairing logic.
+
+All commands will be available in [Applet Command REST API](https://developers.signageos.io/api/#tag/DeviceApplet-Command) and can be downloaded historically as [CSV export](https://developers.signageos.io/api/#tag/DeviceMonitoring/paths/~1v1~1device~1%7BdeviceUid%7D~1report/get).
 
 ## Methods
 
@@ -13,22 +15,40 @@ The `sos.command` API groups together methods for sending logs and receiving com
 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
+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 represents a command structure with a type and additional data.
+ */
 interface ICommand {
     type: string;
+    /**
+     * The `data` property is an object that contains additional data related to the command.
+     */
+    [key: string]: any;
 }
 
 ```
 
+#### Params
+
+| Name      | Type       | Description                   |
+|-----------|------------|-------------------------------|
+| `command` | `TCommand` | The command to be dispatched. |
+
+#### Possible errors
+
+
+- If type contains invalid characters, allowed to are `/^[a-zA-Z0-9\.\-_]+$/g`
+- If the command type is longer then 100 characters limit.
+- If the command is not an object or is missing required properties.
+
 #### Example
 
 ```ts
@@ -41,7 +61,10 @@ await sos.command.dispatch({
 
 :::note[GitHub Example]
 
-- [Sending commands](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/command/sending/)
+- [ Sending commands in Applet](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/command/sending/)
+- [ Rest API - Dispatching commands](https://developers.signageos.io/api/#tag/DeviceApplet-Command/paths/~1v1~1device~1%7BdeviceUid%7D~1applet~1%7BappletUid%7D~1command/post)
+- [ Rest API - Get commands](https://developers.signageos.io/api/#tag/DeviceApplet-Command/paths/~1v1~1device~1%7BdeviceUid%7D~1applet~1command/get)
+- [ Rest API - Receiving historical data](https://developers.signageos.io/api/#tag/DeviceMonitoring/paths/~1v1~1device~1%7BdeviceUid%7D~1report/get)
 
 :::
 
@@ -54,20 +77,43 @@ The `onCommand()` method sets up a listener, which is called whenever a new comm
 ```ts expandable
 onCommand(listener: (command: ICommandEvent) => void): void;
 // show-more
+/**
+ * Received command event interface from signageOS.
+ */
 interface ICommandEvent {
     type: 'command';
+    /**
+     * Command data received from occurred event.
+     */
     command: ICommand;
 }
 
+/**
+ * Interface represents a command structure with a type and additional data.
+ */
 interface ICommand {
     type: string;
+    /**
+     * The `data` property is an object that contains additional data related to the command.
+     */
+    [key: string]: any;
 }
 
 ```
 
+#### Params
+
+| Name       | Type                               | Description                                               |
+|------------|------------------------------------|-----------------------------------------------------------|
+| `listener` | `(command: ICommandEvent) => void` | The listener to be called when a new command is received. |
+
+#### Return value
+
+Resolves when the listener is successfully set up.
+
 :::note[GitHub Example]
 
-- [Receiving commands](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/command/receiving)
+- [ Receiving commands in Applet](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/command/receiving)
 
 :::
 

package/docs/sos/debug.md

@@ -6,11 +6,16 @@ sidebar_position: 0
 
 The `sos.debug` API groups together methods for checking the state of remote debug mode.
 
+:::note
+- This debug is not the "native debug" of the device, but rather a remote debug mode that allows you to connect to the device using Weinre.
+- State of the remote debug mode or native debug mode can be changed via Cloud Control or [Rest API](https://developers-staging.signageos.io/api/#tag/DeviceDebug/paths/~1v1~1device~1%7BdeviceUid%7D~1debug/put).
+:::
+
 ## Methods
 
 ### isRemoteDebugEnabled()
 
-The `isRemoteDebugEnabled()` method returns the state of the [Device debug](https://docs.signageos.io/hc/en-us/articles/4416366711442-Device-debug).
+The `isRemoteDebugEnabled()` method returns the state of the Device debug mode.
 
 ```ts expandable
 isRemoteDebugEnabled(): Promise<boolean>;
@@ -20,7 +25,7 @@ isRemoteDebugEnabled(): Promise<boolean>;
 
 ### onRemoteDebugChanged()
 
-The `onRemoteDebugChanged()` method sets up a listener, which is called whenever the state of the [Device debug](https://docs.signageos.io/hc/en-us/articles/4416366711442-Device-debug) is changed.
+The `onRemoteDebugChanged()` method sets up a listener, which is called whenever the state of the Device debug mode is changed.
 
 ```ts expandable
 onRemoteDebugChanged(listener: (data: {
@@ -28,6 +33,16 @@ onRemoteDebugChanged(listener: (data: {
 }) => void): void;
 ```
 
+#### Params
+
+| Name       | Type                                    | Description                                                                   |
+|------------|-----------------------------------------|-------------------------------------------------------------------------------|
+| `listener` | `(data: { enabled: boolean; }) => void` | The listener to be called when the state of the remote debug mode is changed. |
+
+#### Return value
+
+Resolves when the listener is successfully set up.
+
 ## API Example
 
 ```ts

package/docs/sos/deviceInfo.md

@@ -18,6 +18,17 @@ updated when changed and persisted in local storage.
 getDeviceName(): Promise<string>;
 ```
 
+#### Return value
+
+A promise that resolves to the device name.
+
+#### Example
+
+```ts
+const deviceName = await sos.deviceInfo.getDeviceName();
+console.log(`Device name is: ${deviceName}`);
+```
+
 <Separator />
 
 ### getLocation()
@@ -25,6 +36,10 @@ getDeviceName(): Promise<string>;
 The `getLocation()` method returns location of the device. Location is requested from server on application start, automatically
 updated when changed and persisted in local storage.
 
+:::note
+Location can be set only in CloudControl on Device Info page, or via Rest API.
+:::
+
 ```ts expandable
 getLocation(): Promise<IDeviceLocation | null>;
 // show-more
@@ -36,6 +51,10 @@ interface IDeviceLocation {
 
 ```
 
+#### Return value
+
+A promise that resolves to the device location or `null` if not set.
+
 <Separator />
 
 ### getOrganizationTags()
@@ -43,6 +62,10 @@ interface IDeviceLocation {
 The `getOrganizationTags()` method returns all tags assigned to the device. Tags are requested from server on application start, automatically
 updated when changed and persisted in local storage.
 
+:::note
+Tags can be set only in CloudControl on Device Info page, or via Rest API.
+:::
+
 ```ts expandable
 getOrganizationTags(): Promise<IOrganizationTag[]>;
 // show-more
@@ -52,6 +75,10 @@ interface IOrganizationTag {
 
 ```
 
+#### Return value
+
+A promise that resolves to an array of organization tags.
+
 ## API Example
 
 ```ts

package/docs/sos/display.md

@@ -7,23 +7,54 @@ 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.
-
-- 'FILE_SYSTEM_INTERNAL_STORAGE' -
+The `supports()` method determines whether a queried capability is supported by the device.
 
 ```ts expandable
 supports(capability: DisplayCapability): Promise<boolean>;
 // show-more
+/**
+ * Represents the capabilities that a display can support.
+ * These capabilities are used to determine if a specific feature is available on the display.
+ */
 type DisplayCapability = 'FILE_SYSTEM_INTERNAL_STORAGE' | 'FILE_SYSTEM_EXTERNAL_STORAGE' | 'FILE_SYSTEM_FILE_CHECKSUM' | 'FILE_SYSTEM_LINK' | 'TIMERS_PROPRIETARY' | 'VIDEO_4K' | 'SERIAL' | 'BARCODE_SCANNER' | 'FRONT_OSD' | 'FILE_SYSTEM_CREATE_ARCHIVE' | 'FILE_SYSTEM_ARCHIVE_EXTRACT_INFO' | 'BROWSER' | 'PROXIMITY_SENSOR' | AnyString;
 
 type AnyString = string & {};
 
 ```
 
+#### Params
+
+| Name         | Type                | Description                            |
+|--------------|---------------------|----------------------------------------|
+| `capability` | `DisplayCapability` | - The capability to check for support. |
+
+#### Return value
+
+Resolves to `true` if the capability is supported, otherwise `false`.
+
 ## API Example
 
 ```ts