@signageos/front-applet 7.2.0 → 8.0.1

package/docs/sos/debug.md

@@ -0,0 +1,25 @@
+# debug
+
+The `sos.debug` API groups together methods for checking the state of remote debug mode.
+
+## Methods
+
+### isRemoteDebugEnabled()
+
+The `isRemoteDebugEnabled()` method returns the state of the [Device debug](https://docs.signageos.io/hc/en-us/articles/4416366711442-Device-debug).
+
+```ts expandable
+isRemoteDebugEnabled(): Promise<boolean>;
+```
+
+<Separator />
+
+### 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.
+
+```ts expandable
+onRemoteDebugChanged(listener: (data: {
+    enabled: boolean;
+}) => void): void;
+```

package/docs/sos/deviceInfo.md

@@ -0,0 +1,49 @@
+# deviceInfo
+
+The `sos.deviceInfo` API groups together methods for retrieving information about the device set in the CloudControl, such as location or
+tags.
+
+## Methods
+
+### getDeviceName()
+
+The `getDeviceName()` method returns a name of the device. Name is requested from server on application start, automatically
+updated when changed and persisted in local storage.
+
+```ts expandable
+getDeviceName(): Promise<string>;
+```
+
+<Separator />
+
+### getLocation()
+
+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.
+
+```ts expandable
+getLocation(): Promise<IDeviceLocation | null>;
+// show-more
+interface IDeviceLocation {
+    name: string;
+    customId?: string;
+    description?: string;
+}
+
+```
+
+<Separator />
+
+### getOrganizationTags()
+
+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.
+
+```ts expandable
+getOrganizationTags(): Promise<IOrganizationTag[]>;
+// show-more
+interface IOrganizationTag {
+    name: string;
+}
+
+```

package/docs/sos/display.md

@@ -0,0 +1,21 @@
+# display
+
+The `sos.display` API groups together methods for getting information about the device. Primarily to find out which
+features it supports.
+
+## Methods
+
+### supports()
+
+The `supports()` method determines whether a queried capability is supported.
+
+- 'FILE_SYSTEM_INTERNAL_STORAGE' -
+
+```ts expandable
+supports(capability: DisplayCapability): Promise<boolean>;
+// show-more
+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 & {};
+
+```

package/docs/sos/fileSystem.md

@@ -0,0 +1,594 @@
+# fileSystem
+
+The `sos.fileSystem` API groups together methods for low-level access to the file system. The File System API supports both internal and
+external storage.
+
+:::warning
+
+File System directory structure is **PERSISTENT** and is **NOT** automatically deleted through `Applet Reload` power action!
+Applet Reload only deletes `/data` directory which is reserved for simplified [Offline Cache API](./offline). Use
+`deleteFile()` to clear the device storage file system.
+
+:::
+
+## Methods
+
+### appendFile()
+
+The `writeFile()` method appends string content to the file specified by `filePath`. If the file does exist, it is created. If the directory
+does not exist, an error is thrown.
+
+```ts expandable
+appendFile(filePath: IFilePath, contents: string): Promise<void>;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+#### Possible errors
+
+The method throws an error if the parent directory does not exist or the `filePath` is a directory.
+
+<Separator />
+
+### copyFile()
+
+The `copyFile()` method creates a copy of file at `sourceFilePath` to `destinationFilePath`.
+
+```ts expandable
+copyFile(sourceFilePath: IFilePath, destinationFilePath: IFilePath, options?: ICopyFileOptions): Promise<void>;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+interface ICopyFileOptions {
+    overwrite?: boolean;
+}
+
+```
+
+#### Params
+
+| Name                             | Type      | Description                                                                                    |
+|----------------------------------|-----------|------------------------------------------------------------------------------------------------|
+| `options.overwrite` *(optional)* | `boolean` | If not set or set to `false`, an error will be thrown if `destinationFilePath` already exists. |
+
+#### Possible errors
+
+The method throws an error if the source file does not exists or parent of the destination file path does not exists. It also throws if the
+`options.overwrite` is not set and the destination file path already exists.
+
+<Separator />
+
+### createArchive()
+
+The `createArchive()` method creates an arch file at `archiveFilePath` from `archiveEntries` files.
+
+:::warning
+
+This function is available only on Tizen devices.
+
+:::
+
+```ts expandable
+createArchive(archiveFilePath: IFilePath, archiveEntries: IFilePath[]): Promise<void>;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+<Separator />
+
+### createDirectory()
+
+The `createDirectory()` method create a new directory at specified path.
+
+```ts expandable
+createDirectory(directoryPath: IFilePath): Promise<void>;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+#### Possible errors
+
+The method throws an error if the directory already exists or its parent directory does not exist.
+
+<Separator />
+
+### deleteFile()
+
+The `deleteFile()` method deletes the file specified by `filePath`. To remove a directory set `recursive` to `true`.
+
+```ts expandable
+deleteFile(filePath: IFilePath, recursive: boolean): Promise<void>;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+#### Possible errors
+
+The method throws an error if the file does not exists or if `recursive` is set to false and the file path is a directory.
+
+<Separator />
+
+### downloadFile()
+
+The `downloadFile()` method download a file from `sourceUri` and saves it to the specified path. If the file already exists it is
+overwritten. Optionally, headers for the download request may be specified. A HEAD request is always sent first to get `content-length`
+of the downloaded file.
+
+:::warning
+- For every download request, our app makes HEAD request for `content-length` header on that downloaded file.
+- Windows platform can download only files smaller then 4GB.
+:::
+
+#### Encoding
+
+All downloads respect a standard of `Encoding` with optional compression of files. See [Mozilla standard Accept Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) and [Content Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding).
+
+Download file method is always sending optional following headers:
+```
+Accept-Encoding: gzip
+Accept-Encoding: compress
+Accept-Encoding: deflate
+Accept-Encoding: br
+Accept-Encoding: identity
+Accept-Encoding: *
+```
+
+If the server understands the `Encoding` standard, it compresses files using `gzip` algorithm before the files are sent to the client. If so, the response will contain the following headers:
+```
+Content-Encoding: gzip
+Content-Encoding: compress
+Content-Encoding: deflate
+Content-Encoding: br
+```
+So the data communication is compressed under the hood. The client will automatically decompress data before it's saved to a specified location path. So from JS API point of view, there is no requirement to decompress data by itself.
+
+The standard is supported on all following platforms:
+
+- WebOS 3+
+- Tizen 2.4+
+- Brightsign
+- Raspberry Pi
+- Windows
+
+```ts expandable
+downloadFile(filePath: IFilePath, sourceUri: string, headers?: IHeaders): Promise<void>;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+interface IHeaders {
+    [key: string]: string;
+}
+
+```
+
+#### Possible errors
+
+The method throws an error if the network request fails, parent directory does not exist, or the file path is a directory.
+
+<Separator />
+
+### exists()
+
+The `exists()` method checks whether a file or directory exists.
+
+```ts expandable
+exists(filePath: IFilePath): Promise<boolean>;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+<Separator />
+
+### extractFile()
+
+The `decompressFile()` method decompresses the file at `archiveFilePath` into a new file specified by `destinationDirectoryPath`.
+
+```ts expandable
+extractFile(archiveFilePath: IFilePath, destinationDirectoryPath: IFilePath, method: string): Promise<void>;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+#### Possible errors
+
+The method throws an error if the archive file path does not exist, it is not a valid archive file or the destination directory does not exist.
+
+<Separator />
+
+### getFile()
+
+The `getFile()` method returns runtime information about a file path, such as local url, last modified date or size.
+
+```ts expandable
+getFile(filePath: IFilePath): Promise<IFile | null>;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+interface IFile extends IFilePath {
+    localUri: string;
+    imageThumbnailUriTemplate?: string;
+    videoThumbnailUriTemplate?: string;
+    createdAt?: number;
+    lastModifiedAt?: number;
+    sizeBytes?: number;
+    mimeType?: string;
+}
+
+```
+
+<Separator />
+
+### getFileChecksum()
+
+The `getChecksumFile()` method computes a checksum of the file specified by `filePath`.
+
+```ts expandable
+getFileChecksum(filePath: IFilePath, hashType: HashAlgorithm): Promise<string>;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+type HashAlgorithm = 'md5' | 'sha1' | 'sha256' | 'sha384' | 'sha512' | 'crc32' | AnyString;
+
+type AnyString = string & {};
+
+```
+
+#### Possible errors
+
+The method throws an error if the file does not exist or it is a directory.
+
+<Separator />
+
+### isDirectory()
+
+The `isDirectory()` method checks whether the file path points to a directory.
+
+```ts expandable
+isDirectory(filePath: IFilePath): Promise<boolean>;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+#### Possible errors
+
+The method throws an error if the file path does not exist.
+
+<Separator />
+
+### link()
+
+The `link()` method creates a symbolic link to `sourceFilePath` (existing path) from `destinationFilePath` (new path).
+
+```ts expandable
+link(sourceFilePath: IFilePath, destinationFilePath: IFilePath): Promise<void>;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+<Separator />
+
+### listFiles()
+
+The `listFiles()` method lists all files and directories in the specified path (nested files are not included).
+
+```ts expandable
+listFiles(directoryPath: IFilePath): Promise<IFilePath[]>;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+#### Possible errors
+
+The method throws an error if the path does not exist or it is a file.
+
+<Separator />
+
+### listInternalStorageUnits()
+
+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[]>;
+// show-more
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+<Separator />
+
+### listStorageUnits()
+
+The `listStorageUnits()` method lists all available storage units. All devices always have one internal storage device (with
+`removable: false`) and zero or more external devices. The capacity values are in bytes.
+
+```ts expandable
+listStorageUnits(): Promise<IStorageUnit[]>;
+// show-more
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+<Separator />
+
+### moveFile()
+
+The `moveFile()` method moves a file from `sourceFilePath` to `destinationFilePath`.
+
+```ts expandable
+moveFile(sourceFilePath: IFilePath, destinationFilePath: IFilePath, options?: IMoveFileOptions): Promise<void>;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+interface IMoveFileOptions {
+    overwrite?: boolean;
+}
+
+```
+
+#### Possible errors
+
+The method throws an error if the source file does not exists or parent of the destination file path does not exists. It also throws if the
+`options.overwrite` is not set and the destination file path already exists.
+
+<Separator />
+
+### onStorageUnitsChanged()
+
+The `onStorageUnitsChanged()` method sets up a listener, which is called whenever the list of storage units changes.
+
+```ts expandable
+onStorageUnitsChanged(listener: () => void): void;
+```
+
+<Separator />
+
+### readFile()
+
+The `readFile()` method returns content of the file specified by `filePath`. The file has to be a text file, otherwise the content will be
+mangled.
+
+```ts expandable
+readFile(filePath: IFilePath): Promise<string>;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+#### Possible errors
+
+The method throws an error if the file does not exist.
+
+<Separator />
+
+### removeAllListeners()
+
+The `removeAllListeners()` method removes all listeners, previously added by `removeAllListeners()`
+
+```ts expandable
+removeAllListeners(): void;
+```
+
+<Separator />
+
+### removeStorageUnitsChangedListener()
+
+The `removeStorageUnitsChangedListener()` method removes a listener, previously added by `onStorageUnitsChanged()`
+
+```ts expandable
+removeStorageUnitsChangedListener(listener: () => void): void;
+```
+
+<Separator />
+
+### writeFile()
+
+The `writeFile()` method writes string content to the file specified by `filePath`. If the file does exist, it is created. If the directory
+does not exist, an error is thrown.
+
+```ts expandable
+writeFile(filePath: IFilePath, contents: string): Promise<void>;
+// show-more
+interface IFilePath {
+    storageUnit: IStorageUnit;
+    filePath: string;
+}
+
+interface IStorageUnit {
+    type: string;
+    capacity: number;
+    freeSpace: number;
+    usableSpace: number;
+    removable: boolean;
+}
+
+```
+
+#### Possible errors
+
+The method throws an error if the parent directory does not exist or the `filePath` is a directory.