@signageos/front-applet 8.1.1 → 8.1.3

package/docs/sos/fileSystem.md

@@ -4,69 +4,173 @@ sidebar_position: 0
 
 # fileSystem
 
-<Admonition type="info" icon="" title="">
-  Learn more about using this API [here](https://developers.signageos.io/docs/applets/api-guides/offline-content#storing-files-permanently)
-</Admonition>
-
 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
-
+:::warning Differences between File System API and Offline Cache API
 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.
+:::
 
+:::info GitHub Example
+- [Example usage of File System API in Applet](https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/file-system)
 :::
 
+
+## 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.
+The file system is also shared between all applets, which means you cannot rely on any file system structure on startup because a different applet on the device could have saved files you didn't expect.
+To mitigate this issue, create a directory for your applet and save all files inside it.
+
+```ts
+import sos from '@signageos/front-applet';
+
+sos.onReady(async () => {
+	const storageUnits = await sos.fileSystem.listStorageUnits();
+	const rootPath = {
+		filePath: '', // Empty string is used as an absolute path instead of "/"
+		storageUnit: storageUnits.find((s) => !s.removable), // Find internal storage
+	};
+
+	// This will return files previous applets saved to the device
+	const files = await sos.fileSystem.listFiles(rootPath);
+});
+```
+
 ## 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.
+The `appendFile()` method appends string content to the file specified by `filePath`.
+If the file does exist, it is created.
+
+:::note
+Only string can be appended to the file. If you want to append binary data, you have to convert it to a string first.
+:::
 
 ```ts expandable
 appendFile(filePath: IFilePath, contents: string): Promise<void>;
 // show-more
+/**
+ * Base File System interface for methods.
+ */
 interface IFilePath {
+    /**
+     * Storage unit which is selected for performing file operations.
+     */
     storageUnit: IStorageUnit;
+    /**
+     * File path within the storage unit.
+     */
     filePath: string;
 }
 
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
 ```
 
+#### Params
+
+| Name       | Type        | Description                             |
+|------------|-------------|-----------------------------------------|
+| `filePath` | `IFilePath` | The path to the file to be appended.    |
+| `contents` | `string`    | The content to be appended to the file. |
+
+#### Return value
+
+A promise that resolves when the content is appended successfully.
+
 #### Possible errors
 
-The method throws an error if the parent directory does not exist or the `filePath` is a directory.
+
+- Error If the parent directory does not exist.
+- Error If the `filePath` is a directory.
+- Error If the `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
+- Error If any error occurs during the append operation on the device.
+
+#### Example
+
+```ts
+const filePath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/file.txt',
+};
+
+const contents = 'This is the content to append to the file.';
+await sos.fileSystem.appendFile(filePath, contents);
+```
 
 <Separator />
 
 ### copyFile()
 
-The `copyFile()` method creates a copy of file at `sourceFilePath` to `destinationFilePath`.
+The `copyFile()` method creates a copy of file from `sourceFilePath` to `destinationFilePath`.
 
 ```ts expandable
 copyFile(sourceFilePath: IFilePath, destinationFilePath: IFilePath, options?: ICopyFileOptions): Promise<void>;
 // show-more
+/**
+ * Base File System interface for methods.
+ */
 interface IFilePath {
+    /**
+     * Storage unit which is selected for performing file operations.
+     */
     storageUnit: IStorageUnit;
+    /**
+     * File path within the storage unit.
+     */
     filePath: string;
 }
 
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
@@ -78,116 +182,335 @@ interface ICopyFileOptions {
 
 #### Params
 
-| Name                             | Type      | Description                                                                                    |
-|----------------------------------|-----------|------------------------------------------------------------------------------------------------|
-| `options.overwrite` *(optional)* | `boolean` | If not set or set to `false`, an error will be thrown if `destinationFilePath` already exists. |
+| Name                             | Type               | Description                                                                            |
+|----------------------------------|--------------------|----------------------------------------------------------------------------------------|
+| `sourceFilePath`                 | `IFilePath`        | The path to the file to be copied.                                                     |
+| `destinationFilePath`            | `IFilePath`        | The path where the file will be copied to.                                             |
+| `options` *(optional)*           | `ICopyFileOptions` | Options for copying the file.                                                          |
+| `options.overwrite` *(optional)* | `boolean`          | If set to `true`, the method will overwrite the destination file if it already exists. |
+
+#### Return value
+
+A promise that resolves when the file is copied successfully.
 
 #### 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.
+
+- Error If the source file does not exist.
+- Error If parent of the destination file path does not exist.
+- Error If `options` object is not valid.
+- Error If any error occurs during the copy operation on the device.
+
+#### Example
+
+```ts
+// Copy file from one directory to another and overwrite it if it already exists
+const sourceFilePath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/source/file.txt',
+};
+
+const destinationFilePath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/destination/file.txt',
+};
+
+await sos.fileSystem.copyFile(sourceFilePath, destinationFilePath, { overwrite: true });
+```
 
 <Separator />
 
 ### createArchive()
 
-The `createArchive()` method creates an arch file at `archiveFilePath` from `archiveEntries` files.
+The `createArchive()` method creates an archive file from selected files and directories.
 
 :::warning
+- Never start OR end the `filePath` with a slash - `/`.
+- It is a good practice to check if file exists - `exists()` prior creating it
+:::
 
-This function is available only on Tizen devices.
-
+:::info
+- This function is available only on Tizen devices.
+- All files are added to the archive based on absolute path from root directory.
 :::
 
 ```ts expandable
 createArchive(archiveFilePath: IFilePath, archiveEntries: IFilePath[]): Promise<void>;
 // show-more
+/**
+ * Base File System interface for methods.
+ */
 interface IFilePath {
+    /**
+     * Storage unit which is selected for performing file operations.
+     */
     storageUnit: IStorageUnit;
+    /**
+     * File path within the storage unit.
+     */
     filePath: string;
 }
 
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
 ```
 
+#### Params
+
+| Name              | Type          | Description                                           |
+|-------------------|---------------|-------------------------------------------------------|
+| `archiveFilePath` | `IFilePath`   | The path where the archive file will be created.      |
+| `archiveEntries`  | `IFilePath[]` | An array of file paths to be included in the archive. |
+
+#### Return value
+
+A promise that resolves when the archive file is created successfully.
+
+#### Possible errors
+
+
+- Error If `archiveFilePath` is not a valid object or does not contain `storageUnit` and `filePath`.
+- Error If `archiveEntries` is not a valid array of objects.
+- Error If the parent directory of `archiveFilePath` does not exist.
+- Error If any of the `archiveEntries` do not exist or are directories.
+- Error If creating the archive file fails.
+- Error If the platform does not support creating archive files.
+
+#### Example
+
+```ts
+const archiveFilePath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/archive.zip',
+};
+
+const archiveEntries = [
+	{
+		storageUnit: internalStorageUnit,
+		filePath: 'path/to/file1.txt',
+	},
+	{
+		storageUnit: internalStorageUnit,
+		filePath: 'path/to/file2.txt',
+	},
+	{
+		storageUnit: internalStorageUnit,
+		filePath: 'path/to/directory1',
+	},
+];
+
+await sos.fileSystem.createArchive(archiveFilePath, archiveEntries);
+```
+
 <Separator />
 
 ### createDirectory()
 
 The `createDirectory()` method create a new directory at specified path.
 
+:::warning
+- Never start OR end the filePath with a slash - `/`.
+- It is a good practice to check if directory exists - `isDirectory()` prior creating it.
+:::
+
 ```ts expandable
 createDirectory(directoryPath: IFilePath): Promise<void>;
 // show-more
+/**
+ * Base File System interface for methods.
+ */
 interface IFilePath {
+    /**
+     * Storage unit which is selected for performing file operations.
+     */
     storageUnit: IStorageUnit;
+    /**
+     * File path within the storage unit.
+     */
     filePath: string;
 }
 
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
 ```
 
+#### Params
+
+| Name            | Type        | Description                                       |
+|-----------------|-------------|---------------------------------------------------|
+| `directoryPath` | `IFilePath` | The path where the new directory will be created. |
+
+#### Return value
+
+A promise that resolves when the directory is created successfully.
+
 #### Possible errors
 
-The method throws an error if the directory already exists or its parent directory does not exist.
+
+- Error If `directoryPath` is not a valid object or does not contain `storageUnit` and `filePath`.
+- Error If the directory already exists.
+- Error If parent directory does not exist.
+
+#### Example
+
+```ts
+const internalStorageUnit = (await sos.fileSystem.listInternalStorageUnits())[0];
+const directoryPath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/new/directory',
+};
+
+await sos.fileSystem.createDirectory(directoryPath);
+```
 
 <Separator />
 
 ### deleteFile()
 
-The `deleteFile()` method deletes the file specified by `filePath`. To remove a directory set `recursive` to `true`.
+The `deleteFile()` method deletes the file specified by `filePath`.
 
 ```ts expandable
 deleteFile(filePath: IFilePath, recursive: boolean): Promise<void>;
 // show-more
+/**
+ * Base File System interface for methods.
+ */
 interface IFilePath {
+    /**
+     * Storage unit which is selected for performing file operations.
+     */
     storageUnit: IStorageUnit;
+    /**
+     * File path within the storage unit.
+     */
     filePath: string;
 }
 
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
 ```
 
+#### Params
+
+| Name        | Type        | Description                                                                              |
+|-------------|-------------|------------------------------------------------------------------------------------------|
+| `filePath`  | `IFilePath` | The path to the file or directory to be deleted.                                         |
+| `recursive` | `boolean`   | If set to `true`, the method will delete the directory and all its contents recursively. |
+
+#### Return value
+
+A promise that resolves when the file is deleted successfully.
+
 #### 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.
+
+- Error If `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
+- Error If the file does not exist or if `recursive` is set to false and the file path is a directory.
+- Error If deleting path does not exist.
+- Error When is deleting directory and is not empty (not recursive).
+
+#### Example
+
+```ts
+// Delete directory and all files inside
+//// First check, if there is such a directory
+if (await sos.fileSystem.exists({ storageUnit: internalStorageUnit, filePath: 'test-dir' })) {
+    // Delete the directory and all it's content recursively
+    await sos.fileSystem.deleteFile({ storageUnit: internalStorageUnit, filePath: 'test-dir' }, true);
+}
+
+// Delete file
+//// First check, if there is such a file
+if (await sos.fileSystem.exists({ storageUnit: internalStorageUnit, filePath: 'test-dir/downloaded-file.png' })) {
+    // Delete the file
+    await sos.fileSystem.deleteFile({ storageUnit: internalStorageUnit, filePath: 'test-dir/downloaded-file.png' }, false);
+}
+```
 
 <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.
+The `downloadFile()` method download a file from `sourceUri` and saves it to the specified path. If the file already exists, the file will be
+overwritten. Optionally, headers for the download request may be specified.
 
-:::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.
+:::danger
+For every download request, our Core Apps makes HEAD request for `content-length` header on that downloaded file. It's due to determining if device has enough space to download the file.
 :::
 
 #### 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:
@@ -220,16 +543,43 @@ The standard is supported on all following platforms:
 ```ts expandable
 downloadFile(filePath: IFilePath, sourceUri: string, headers?: IHeaders): Promise<void>;
 // show-more
+/**
+ * Base File System interface for methods.
+ */
 interface IFilePath {
+    /**
+     * Storage unit which is selected for performing file operations.
+     */
     storageUnit: IStorageUnit;
+    /**
+     * File path within the storage unit.
+     */
     filePath: string;
 }
 
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
@@ -239,9 +589,40 @@ interface IHeaders {
 
 ```
 
+#### Params
+
+| Name                   | Type        | Description                                                                                                                     |
+|------------------------|-------------|---------------------------------------------------------------------------------------------------------------------------------|
+| `filePath`             | `IFilePath` | The path where the downloaded file will be saved.                                                                               |
+| `sourceUri`            | `string`    | The URI of the file to be downloaded.                                                                                           |
+| `headers` *(optional)* | `IHeaders`  | Key, value pairs of HTTP headers to send along with the request. Used when the target file is protected by a password or if any |
+
+#### Return value
+
+A promise that resolves when the file is downloaded successfully.
+
 #### Possible errors
 
-The method throws an error if the network request fails, parent directory does not exist, or the file path is a directory.
+
+- Error If `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
+- Error If `sourceUri` is not a valid URI.
+- Error If `headers` is not a valid object.
+- Error If the parent directory of `filePath` does not exist.
+- Error If the network request fails.
+
+#### Example
+
+```ts
+const filePath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/downloaded/file.zip',
+};
+const sourceUri = 'https://example.com/path/to/file.zip';
+const headers = {
+	'Authorization': 'Bearer your_token_here',
+};
+await sos.fileSystem.downloadFile(filePath, sourceUri, headers);
+```
 
 <Separator />
 
@@ -252,48 +633,169 @@ The `exists()` method checks whether a file or directory exists.
 ```ts expandable
 exists(filePath: IFilePath): Promise<boolean>;
 // show-more
+/**
+ * Base File System interface for methods.
+ */
 interface IFilePath {
+    /**
+     * Storage unit which is selected for performing file operations.
+     */
     storageUnit: IStorageUnit;
+    /**
+     * File path within the storage unit.
+     */
     filePath: string;
 }
 
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
 ```
 
+#### Params
+
+| Name       | Type        | Description                                 |
+|------------|-------------|---------------------------------------------|
+| `filePath` | `IFilePath` | The path to the file or directory to check. |
+
+#### Return value
+
+A promise that resolves to `true` if the file or directory exists, `false` otherwise.
+
+#### Possible errors
+
+
+- Error If the `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
+- Error If any error occurs during the existence check operation on the device.
+
+#### Example
+
+```ts
+const filePath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/file.txt',
+};
+
+const fileExists = await sos.fileSystem.exists(filePath);
+console.log(`File exists: ${fileExists}`); // Prints true if the file exists, false otherwise
+```
+
 <Separator />
 
 ### extractFile()
 
-The `decompressFile()` method decompresses the file at `archiveFilePath` into a new file specified by `destinationDirectoryPath`.
+The `extractFile()` method extract (recursively) the archive file at `archiveFilePath` into a new file specified by `destinationDirectoryPath`.
+
+:::note
+- The directory/folder you are extracting your ZIP file into has to be created BEFORE you start extracting the ZIP.
+- Only supported extract method is `zip`.
+:::
 
 ```ts expandable
-extractFile(archiveFilePath: IFilePath, destinationDirectoryPath: IFilePath, method: string): Promise<void>;
+extractFile(archiveFilePath: IFilePath, destinationDirectoryPath: IFilePath, method: ExtractMethodType): Promise<void>;
 // show-more
+/**
+ * Base File System interface for methods.
+ */
 interface IFilePath {
+    /**
+     * Storage unit which is selected for performing file operations.
+     */
     storageUnit: IStorageUnit;
+    /**
+     * File path within the storage unit.
+     */
     filePath: string;
 }
 
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
+/**
+ * Allowed extract method types for `extractFile()` operations.
+ */
+type ExtractMethodType = 'zip' | AnyString;
+
+type AnyString = string & {};
+
 ```
 
+#### Params
+
+| Name                       | Type                | Description                                                           |
+|----------------------------|---------------------|-----------------------------------------------------------------------|
+| `archiveFilePath`          | `IFilePath`         | The path to the archive file to be decompressed.                      |
+| `destinationDirectoryPath` | `IFilePath`         | The path to the directory where the decompressed files will be saved. |
+| `method`                   | `ExtractMethodType` | Extract method to use for extracting, e.g. 'zip'.                     |
+
 #### 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.
+
+- Error If the archive file path does not exist.
+- Error If it is not a valid archive file.
+- Error If destination directory does not exist.
+
+#### Example
+
+```ts
+const archiveFilePath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/archive.zip',
+};
+
+const destinationDirectoryPath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/destination/directory',
+};
+
+await sos.fileSystem.extractFile(archiveFilePath, destinationDirectoryPath, 'zip');
+```
 
 <Separator />
 
@@ -301,32 +803,108 @@ The method throws an error if the archive file path does not exist, it is not a
 
 The `getFile()` method returns runtime information about a file path, such as local url, last modified date or size.
 
+:::warning
+Return statement is a dynamic object! It has to be always generated and retrieved by this JS API, as the values in localUri differ platform by platform. Never generate the object manually. `{"localUri":"file://internal/path/to/file.txt"}` is for demonstration only.
+:::
+
 ```ts expandable
 getFile(filePath: IFilePath): Promise<IFile | null>;
 // show-more
+/**
+ * Properties of returned file from File System API.
+ */
+interface IFile extends IFilePath {
+    localUri: string;
+    /**
+     * Image thumbnail URI of the file, which can be used to display a preview of the file.
+     * Note: Supported only on Linux.
+     */
+    imageThumbnailUriTemplate?: string;
+    /**
+     * Video thumbnail URI of the file, which can be used to display a preview of the file.
+     * Note: Supported only on Linux.
+     */
+    videoThumbnailUriTemplate?: string;
+    /**
+     * Date and time when the file was created in milliseconds since the epoch.
+     */
+    createdAt?: number;
+    lastModifiedAt?: number;
+    sizeBytes?: number;
+    mimeType?: string;
+}
+
+/**
+ * Base File System interface for methods.
+ */
 interface IFilePath {
+    /**
+     * Storage unit which is selected for performing file operations.
+     */
     storageUnit: IStorageUnit;
+    /**
+     * File path within the storage unit.
+     */
     filePath: string;
 }
 
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
-interface IFile extends IFilePath {
-    localUri: string;
-    imageThumbnailUriTemplate?: string;
-    videoThumbnailUriTemplate?: string;
-    createdAt?: number;
-    lastModifiedAt?: number;
-    sizeBytes?: number;
-    mimeType?: string;
-}
+```
+
+#### Params
+
+| Name       | Type        | Description                           |
+|------------|-------------|---------------------------------------|
+| `filePath` | `IFilePath` | The path to the file to be retrieved. |
+
+#### Return value
+
+A promise that resolves to the file information or `null` if the file does not exist.
 
+#### Possible errors
+
+
+- Error If the `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
+- Error If the file is a directory.
+- Error If any error occurs during the retrieval operation on the device.
+
+#### Example
+
+```ts
+// Get file information
+const filePath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/file.txt',
+};
+
+const fileInfo = await sos.fileSystem.getFile(filePath);
+console.log(JSON.stringify(fileInfo)); // Prints the file information
+console.log(fileInfo.localUri); // Prints the local URI of the file
 ```
 
 <Separator />
@@ -335,31 +913,93 @@ interface IFile extends IFilePath {
 
 The `getChecksumFile()` method computes a checksum of the file specified by `filePath`.
 
+:::warning Tizen limitation
+If you are about to use the MD5 file validation it will automatically return on any Samsung Tizen - 2.4, 3.0 and 4.0.
+Reason: MD5 file checksum is not available on any Tizen displays due to the Samsung restriction.
+:::
+
 ```ts expandable
 getFileChecksum(filePath: IFilePath, hashType: HashAlgorithm): Promise<string>;
 // show-more
+/**
+ * Base File System interface for methods.
+ */
 interface IFilePath {
+    /**
+     * Storage unit which is selected for performing file operations.
+     */
     storageUnit: IStorageUnit;
+    /**
+     * File path within the storage unit.
+     */
     filePath: string;
 }
 
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
-type HashAlgorithm = 'md5' | 'sha1' | 'sha256' | 'sha384' | 'sha512' | 'crc32' | AnyString;
+/**
+ * Represents the supported hash algorithms by Core Apps.
+ */
+type HashAlgorithm = 'md5' | 'crc32' | AnyString;
 
 type AnyString = string & {};
 
 ```
 
+#### Params
+
+| Name       | Type            | Description                                                   |
+|------------|-----------------|---------------------------------------------------------------|
+| `filePath` | `IFilePath`     | The path to the file for which the checksum will be computed. |
+| `hashType` | `HashAlgorithm` | The type of hash algorithm to use for computing the checksum. |
+
+#### Return value
+
+A promise that resolves to the computed checksum of the file.
+
 #### Possible errors
 
-The method throws an error if the file does not exist or it is a directory.
+
+- Error If `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
+- Error If `hashType` is not a valid type or string.
+- Error If the file does not exist.
+- Error If `filepath` it is a directory
+
+#### Example
+
+```ts
+const filePath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/file.txt',
+};
+
+const checksum = await sos.fileSystem.getFileChecksum(filePath, 'md5');
+console.log(`Checksum of the file: ${checksum}`);
+```
 
 <Separator />
 
@@ -370,49 +1010,169 @@ The `isDirectory()` method checks whether the file path points to a directory.
 ```ts expandable
 isDirectory(filePath: IFilePath): Promise<boolean>;
 // show-more
+/**
+ * Base File System interface for methods.
+ */
 interface IFilePath {
+    /**
+     * Storage unit which is selected for performing file operations.
+     */
     storageUnit: IStorageUnit;
+    /**
+     * File path within the storage unit.
+     */
     filePath: string;
 }
 
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
 ```
 
+#### Params
+
+| Name       | Type        | Description             |
+|------------|-------------|-------------------------|
+| `filePath` | `IFilePath` | The file path to check. |
+
+#### Return value
+
+A promise that resolves to `true` if the file path is a directory, `false` otherwise.
+
 #### Possible errors
 
-The method throws an error if the file path does not exist.
+
+- Error If `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
+- Error If the file path does not exist.
+
+#### Example
+
+```ts
+const filePath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/directory',
+};
+const isDir = await sos.fileSystem.isDirectory(filePath);
+if (isDir) {
+	console.log('The file path is a directory.');
+} else {
+	console.log('The file path is not a directory.');
+}
+```
 
 <Separator />
 
 ### link()
 
-The `link()` method creates a symbolic link to `sourceFilePath` (existing path) from `destinationFilePath` (new path).
+The `link()` method creates a symbolic link from `sourceFilePath` (existing path) to `destinationFilePath` (new path).
+
+:::note
+This method is only available on Linux devices.
+:::
 
 ```ts expandable
 link(sourceFilePath: IFilePath, destinationFilePath: IFilePath): Promise<void>;
 // show-more
+/**
+ * Base File System interface for methods.
+ */
 interface IFilePath {
+    /**
+     * Storage unit which is selected for performing file operations.
+     */
     storageUnit: IStorageUnit;
+    /**
+     * File path within the storage unit.
+     */
     filePath: string;
 }
 
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
 ```
 
+#### Params
+
+| Name                  | Type        | Description                                                          |
+|-----------------------|-------------|----------------------------------------------------------------------|
+| `sourceFilePath`      | `IFilePath` | The path to the existing file or directory that you want to link to. |
+| `destinationFilePath` | `IFilePath` | The path where the symbolic link will be created.                    |
+
+#### Return value
+
+A promise that resolves when the symbolic link is created successfully.
+
+#### Possible errors
+
+
+- Error If `sourceFilePath` or `destinationPath` is not a valid object or does not contain `storageUnit` and `filePath`.
+- Error If the `sourceFilePath` does not exist or if the `destinationFilePath` already exists.
+- Error The platform does not support linking directories.
+
+#### Example
+
+```ts
+const internalStorageUnit = (await sos.fileSystem.listInternalStorageUnits())[0];
+const sourceFilePath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/existing/file.txt',
+};
+
+const destinationFilePath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/symlink/file_link.txt',
+};
+
+await sos.fileSystem.link(sourceFilePath, destinationFilePath);
+```
+
 <Separator />
 
 ### listFiles()
@@ -422,24 +1182,80 @@ The `listFiles()` method lists all files and directories in the specified path (
 ```ts expandable
 listFiles(directoryPath: IFilePath): Promise<IFilePath[]>;
 // show-more
+/**
+ * Base File System interface for methods.
+ */
 interface IFilePath {
+    /**
+     * Storage unit which is selected for performing file operations.
+     */
     storageUnit: IStorageUnit;
+    /**
+     * File path within the storage unit.
+     */
     filePath: string;
 }
 
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
 ```
 
+#### Params
+
+| Name            | Type        | Description                                           |
+|-----------------|-------------|-------------------------------------------------------|
+| `directoryPath` | `IFilePath` | The path to the directory where files will be listed. |
+
+#### Return value
+
+A promise that resolves to an array of file paths in the specified directory.
+
 #### Possible errors
 
-The method throws an error if the path does not exist or it is a file.
+
+- Error If `directoryPath` is not a valid object or does not contain `storageUnit` and `filePath`.
+- Error If the path does not exist, or it is a file.
+
+#### Example
+
+```ts
+// List files in the root directory of the internal storage unit
+const internalStorageUnit = (await sos.fileSystem.listInternalStorageUnits())[0];
+const directoryPath = {
+	storageUnit: internalStorageUnit,
+	filePath: '', // Empty string is used as an absolute path instead of "/"
+};
+
+const files = await sos.fileSystem.listFiles(directoryPath);
+console.log('Files in the root directory:', files.length);
+files.forEach((file) => {
+	console.log(`File: ${file.filePath}`);
+});
+```
 
 <Separator />
 
@@ -450,16 +1266,51 @@ A shorthand method for listing only the internal storage units (i.e. those with
 ```ts expandable
 listInternalStorageUnits(): Promise<IStorageUnit[]>;
 // show-more
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
 ```
 
+#### Return value
+
+An array of internal storage units available on the device.
+
+#### Example
+
+```ts
+// List internal storage units
+const internalStorageUnits = await sos.fileSystem.listInternalStorageUnits();
+internalStorageUnits.forEach((storageUnit) => {
+  console.log(`Storage Unit Type: ${storageUnit.type}`);
+  console.log(`Capacity: ${storageUnit.capacity} bytes`);
+  console.log(`Free Space: ${storageUnit.freeSpace} bytes`);
+  console.log(`Usable Space: ${storageUnit.usableSpace} bytes`);
+});
+```
+
 <Separator />
 
 ### listStorageUnits()
@@ -467,19 +1318,65 @@ interface IStorageUnit {
 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.
 
+:::note
+This is a mandatory method that is required for all the other File System APIs. The other APIs require a storageUnit object that is retrieved from this method to manipulate with files on a correct storage location (internal/external).
+:::
+
+:::warning
+`storageUnit` is a dynamic object! It has to be always generated and retrieved by this JS API, as the values in type differ platform by platform. Never generate the object manually. `{"type":"internal"}` is for demonstration only.
+:::
+
 ```ts expandable
 listStorageUnits(): Promise<IStorageUnit[]>;
 // show-more
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
 ```
 
+#### Return value
+
+An array of storage units available on the device.
+
+#### Possible errors
+
+InternalFileSystemError Unexpected error occurred when listing storage units.
+
+#### Example
+
+```ts
+// Storage units are equivalent to disk volumes (C:, D: etc on Windows; /mnt/disc1, /mnt/disc2 on Unix)
+const storageUnits = await sos.fileSystem.listStorageUnits();
+const externalStorageUnits = storageUnits.filter((storageUnit) => storageUnit.removable);
+externalStorageUnits.forEach((storageUnit) => {
+ console.log(`Storage Unit Type: ${storageUnit.type}`);
+console.log(`Capacity: ${storageUnit.capacity} bytes`);
+});
+```
+
 <Separator />
 
 ### moveFile()
@@ -489,16 +1386,43 @@ The `moveFile()` method moves a file from `sourceFilePath` to `destinationFilePa
 ```ts expandable
 moveFile(sourceFilePath: IFilePath, destinationFilePath: IFilePath, options?: IMoveFileOptions): Promise<void>;
 // show-more
+/**
+ * Base File System interface for methods.
+ */
 interface IFilePath {
+    /**
+     * Storage unit which is selected for performing file operations.
+     */
     storageUnit: IStorageUnit;
+    /**
+     * File path within the storage unit.
+     */
     filePath: string;
 }
 
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
@@ -508,10 +1432,43 @@ interface IMoveFileOptions {
 
 ```
 
+#### Params
+
+| Name                             | Type               | Description                                                                            |
+|----------------------------------|--------------------|----------------------------------------------------------------------------------------|
+| `sourceFilePath`                 | `IFilePath`        | The path to the file to be moved.                                                      |
+| `destinationFilePath`            | `IFilePath`        | The path where the file will be moved to.                                              |
+| `options` *(optional)*           | `IMoveFileOptions` | Options for moving the file.                                                           |
+| `options.overwrite` *(optional)* | `boolean`          | If set to `true`, the method will overwrite the destination file if it already exists. |
+
+#### Return value
+
+A promise that resolves when the file is moved successfully.
+
 #### 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.
+
+- Error If the source file does not exist or parent of the destination file path does not exist.
+- Error If the `options.overwrite` is not set and the destination file path already exists.
+- Error If deleting path does not exist.
+- Error If any error occurs during the move operation on the device.
+
+#### Example
+
+```ts
+// Move file from one directory to another and overwrite it if it already exists
+const sourceFilePath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/source/file.txt',
+};
+
+const destinationFilePath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/destination/file.txt',
+};
+
+await sos.fileSystem.moveFile(sourceFilePath, destinationFilePath, { overwrite: true });
+```
 
 <Separator />
 
@@ -523,40 +1480,103 @@ The `onStorageUnitsChanged()` method sets up a listener, which is called wheneve
 onStorageUnitsChanged(listener: () => void): void;
 ```
 
+#### Params
+
+| Name       | Type         | Description                                                       |
+|------------|--------------|-------------------------------------------------------------------|
+| `listener` | `() => void` | The listener function to be called when the storage units change. |
+
+#### Possible errors
+
+Error If `listener` is not a valid function.
+
 <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.
+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
+/**
+ * Base File System interface for methods.
+ */
 interface IFilePath {
+    /**
+     * Storage unit which is selected for performing file operations.
+     */
     storageUnit: IStorageUnit;
+    /**
+     * File path within the storage unit.
+     */
     filePath: string;
 }
 
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
 ```
 
+#### Params
+
+| Name       | Type        | Description                      |
+|------------|-------------|----------------------------------|
+| `filePath` | `IFilePath` | The path to the file to be read. |
+
+#### Return value
+
+A promise that resolves to the content of the file.
+
 #### Possible errors
 
-The method throws an error if the file does not exist.
+
+- Error If the file does not exist.
+- Error If the `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
+- Error If the file is a directory.
+- Error If any error occurs during the read operation on the device.
+
+#### Example
+
+```ts
+const filePath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/file.txt',
+};
+
+const fileContent = await sos.fileSystem.readFile(filePath);
+console.log(`Content of the file: ${fileContent}`);
+```
 
 <Separator />
 
 ### removeAllListeners()
 
-The `removeAllListeners()` method removes all listeners, previously added by `removeAllListeners()`
+The `removeAllListeners()` method removes all listeners, previously added by `onStorageUnitsChanged()`
 
 ```ts expandable
 removeAllListeners(): void;
@@ -578,43 +1598,99 @@ removeStorageUnitsChangedListener(listener: () => void): void;
 
 The `wipeout()` method is used to wipe out all data from the file system, later when action is finished the device is rebooted.
 
+```ts expandable
+wipeout(): Promise<void>;
+```
+
+#### Return value
+
+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.
 :::
 
-```ts expandable
-wipeout(): Promise<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.
+The `writeFile()` method writes string content to the file specified by `filePath`. If the file does exist, it is created.
 
 ```ts expandable
 writeFile(filePath: IFilePath, contents: string): Promise<void>;
 // show-more
+/**
+ * Base File System interface for methods.
+ */
 interface IFilePath {
+    /**
+     * Storage unit which is selected for performing file operations.
+     */
     storageUnit: IStorageUnit;
+    /**
+     * File path within the storage unit.
+     */
     filePath: string;
 }
 
+/**
+ * File System Storage Unit returned by the File System API.
+ */
 interface IStorageUnit {
+    /**
+     * The type of the storage unit, e.g., "internal" or "external".
+     */
     type: string;
+    /**
+     * The total capacity of the storage unit in bytes.
+     */
     capacity: number;
+    /**
+     * The amount of free space available in the storage unit in bytes.
+     */
     freeSpace: number;
+    /**
+     * The amount of usable space in the storage unit in bytes.
+     */
     usableSpace: number;
+    /**
+     * Indicates whether the storage unit is removable (e.g., an SD card).
+     */
     removable: boolean;
 }
 
 ```
 
+#### Params
+
+| Name       | Type        | Description                            |
+|------------|-------------|----------------------------------------|
+| `filePath` | `IFilePath` | The path to the file to be written.    |
+| `contents` | `string`    | The content to be written to the file. |
+
+#### Return value
+
+A promise that resolves when the content is written successfully.
+
 #### Possible errors
 
-The method throws an error if the parent directory does not exist or the `filePath` is a directory.
+
+- Error If the parent directory does not exist or the `filePath` is a directory.
+- Error If the `filePath` is not a valid object or does not contain `storageUnit` and `filePath`.
+- Error If any error occurs during the write operation on the device.
+
+#### Example
+
+```ts
+const filePath = {
+	storageUnit: internalStorageUnit,
+	filePath: 'path/to/file.txt',
+};
+
+const contents = 'This is the content to write to the file.';
+await sos.fileSystem.writeFile(filePath, contents);
+```
 
 ## API Example