@signageos/front-applet 8.1.3 → 8.2.0

package/es6/FrontApplet/Offline/Cache/Cache.d.ts

@@ -11,15 +11,14 @@ import IChecksumMessage from './IChecksumMessage';
 import IOfflineCache from './IOfflineCache';
 import { HashAlgorithm } from '../../FileSystem/HashAlgorithm';
 /**
- * The `sos.offline` API groups together methods used to download and save arbitrary files, which can be accessed even if the device is offline.
+ * The `sos.offline.cache` API groups together methods used to download and save arbitrary files, which can be accessed even if the device is offline.
  *
- * :::warning
+ * > Please refer to difference between `sos.offline.cache` and `sos.fileSystem` APIs in our [documentation](http://localhost:3000/sdk/sos/offline/).
  *
+ * :::warning
  * Emulator has certain limitations while handling offline files. [Read more here](https://docs.signageos.io/hc/en-us/articles/4405238997138)
- *
  * :::
  *
- * @tutorial https://developers.signageos.io/docs/applets/api-guides/offline-content#caching-audio-visual-content-or-arbitrary-data-sosofflinecache
  */
 export default class Cache implements IOfflineCache {
     private messagePrefix;
@@ -30,101 +29,279 @@ export default class Cache implements IOfflineCache {
     /** @internal */
     constructor(messagePrefix: string, postMessage: IPostMessage<ISavedFileMessage & ISavedContentMessage & ILoadedFileMessage & ILoadedContentMessage & IListedFilesMessage & IListedContentsMessage & IChecksumMessage & IValidatedChecksumMessage>);
     /**
-     * The `listFiles()` method list all currently cached files.
+     * The `listFiles()` method list all currently cached files in internal storage, which was previously saved by `saveFile()` or `loadOrSaveFile()` methods.
      *
+     * @returns {Promise<string[]>} A promise that resolves to an array of unique identifiers (uids) of the saved files.
+     * @throws Error If any error occurs during listing files.
+     * @throws Error If the files cannot be listed.
      * @since 2.0.0
+     *
+     * @example
+     * await sos.offline.cache.saveFile('example-file.mp4', 'https://example.com/path/to/your/file.mp4');
+     * await sos.offline.cache.saveFile('another-file.jpg', 'https://example.com/path/to/your/image.jpg');
+     *
+     * // Later list the saved files
+     * const files = await sos.offline.cache.listFiles();
+     * console.log('Saved files:', files); // Output: Saved files: ['example-file.mp4', 'another-file.jpg']
      */
     listFiles(): Promise<string[]>;
     /**
      * The `loadFile()` method loads cached file, which was previously saved by `saveFile()` or `loadOrSaveFile()` methods.
      *
-     * @throws If the uid does not exists
-     *
+     * @param uid Unique identifier of the file to be loaded.
+     * @returns {Promise<IFile>} A promise that resolves to the loaded file.
+     * @throws Error If the uid is not a valid string.
+     * @throws Error If the uid does not exist
      * @since 1.0.3
+     *
+     * @example
+     * // Save a file
+     * await sos.offline.cache.saveFile('example-file.mp4', 'https://example.com/path/to/your/file.mp4');
+     * // Later load the file
+     * const file = await sos.offline.cache.loadFile('example-file.mp4');
+     * console.log('Loaded file:', file); // Output: Loaded file: { uid: 'example-file.mp4', uri: 'file://path/to/your/file.mp4' }
      */
     loadFile(uid: string): Promise<IFile>;
     /**
-     * The `saveFile()` method downloads file from `uri` and saves it to the offline cache.
-     *
-     * :::warning
-     *
-     * `uid` should have the same file extension (e.g.: mp4, svg, jpg) as the original file.
+     * Method `saveFile()` is used to save files from remote a destination into the device internal memory.
      *
+     * :::info
+     * - Local device file path differs from device to device. It can point to `file://` or `http://localhost` etc.
      * :::
      *
-     * @throws If the network request fails or a file with the same uid is already cached
+     * :::warning
+     * - headers has to be a JSON object. If you are passing the value, make sure you use JSON.parse().
+     * - `uid` should have the same file extension (e.g.: mp4, svg, jpg) as the original file.
+     * :::
      *
+     * @param uid Unique identifier of the file to be saved.
+     * @param uri URI of the file to be downloaded.
+     * @param headers 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 other specific headers are needed to access it.
+     * @throws Error If the network request fails.
+     * @throws Error If the uid is not a valid string.
+     * @throws Error If the uri is not a valid URI.
+     * @throws Error File with the same uid is already cached.
+     * @throws Error If the headers are not a valid object with string values.
      * @since 1.0.3
+     *
+     * @example
+     * await sos.offline.cache.saveFile('example-file.mp4', 'https://example.com/path/to/your/file.mp4')
+     * 	.then(() => {
+     * 		console.log('File saved successfully');
+     *  })
+     *  .catch((error) => {
+     * 		console.error('Error saving file:', error);
+     * });
      */
     saveFile(uid: string, uri: string, headers?: {
         [key: string]: string;
     }): Promise<void>;
     /**
-     * The loadOrSaveFile() method loads the file from the cache, or downloads it if it's not already cached.
+     * Method `loadOrSaveFile()` is used for individual file retrieval & save in case when file is not saved in local storage yet. To get file from internal memory & save it when not yet exists we prepared `loadOrSaveFile()` method.
+     *
+     * :::info
+     * - The file URI has to return the file. If your URI leads to a 303 redirect (e.g. from http to https), the API will not work.
+     * - Emulator has certain limitations while handling offline files. [Read more here](https://docs.signageos.io/hc/en-us/articles/4405238997138).
+     * - Local device file path differs from device to device. It can point to `file://` or `http://localhost` etc.
+     * :::
+     *
+     * :::warning
+     * `uid` should have the same file extension (e.g.: mp4, svg, jpg) as the original file
+     * :::
      *
+     * @param uid Unique identifier of the file to be loaded or saved.
+     * @param uri URI of the file to be downloaded if not cached.
+     * @param headers 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 other specific headers are needed to access it.
+     * @returns {Promise<IFile>} A promise that resolves to the loaded or saved file.
+     * @throws Error If the uid is not a valid string.
+     * @throws Error If the uri is not a valid URI.
+     * @throws Error If the headers are not a valid object with string values.
+     * @throws Error If the file cannot be loaded or saved.
+     * @throws AppletOfflineCacheError If the headers are not valid.
      * @since 1.0.9
+     * @example // {@link https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/offline-files | Example Applet with Offline Files}
+     * @example // {@link https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/video-loop-offline | Example Applet with Video Loop Offline}
+     *
+     * @example
+     * await sos.offline.cache.loadOrSaveFile('example-file.mp4', 'https://example.com/path/to/your/file.mp4')
+     * 	.then((file) => {
+     * 		console.log('File loaded or saved:', file);
+     * 	})
+     * 	.catch((error) => {
+     * 		console.error('Error loading or saving file:', error);
+     * });
      */
     loadOrSaveFile(uid: string, uri: string, headers?: {
         [key: string]: string;
     }): Promise<IFile>;
     /**
-     * The `deleteFile()` method removes the file specified by `uid`.
+     * The `deleteFile()` method removes the file specified by `uid` from cache storage.
      *
+     * @param uid Unique identifier of the file to be deleted.
+     * @returns {Promise<void>} A promise that resolves when the file is deleted.
+     * @throws Error If the uid is not a valid string.
+     * @throws Error If the uid is not found in the cache.
      * @since 2.0.0
      *
-     * @throws If the uid does not exist.
+     * @example
+     * // Save a file
+     * await sos.offline.cache.saveFile('example-file.mp4', 'https://example.com/path/to/your/file.mp4');
+     * // Later delete the file
+     * await sos.offline.cache.deleteFile('example-file.mp4');
      */
     deleteFile(uid: string): Promise<void>;
     /**
      * The `listContent()` method lists all values saved by `saveContent()` method.
      *
+     * @returns {Promise<string[]>} A promise that resolves to an array of saved content.
      * @since 2.0.0
-     * @tutorial https://developers.signageos.io/docs/applets/api-guides/key-value-storage
+     *
+     * @example
+     * // Save some content and list all saved contents
+     * await sos.offline.cache.saveContent('ApplicationSecret', '123SuperSecretHash');
+     * await sos.offline.cache.saveContent('UserToken', 'abc123xyz');
+     *
+     * // Later list the saved contents
+     * const contents = await sos.offline.cache.listContents();
+     * console.log('Saved contents:', contents); // Output: Saved contents: ['ApplicationSecret', 'UserToken']
      */
     listContents(): Promise<string[]>;
     /**
      * The `loadContent()` method gets the value specified by `uid`, which was previously saved by `saveContent()`.
      *
+     * @param uid Unique identifier of the content to be loaded.
+     * @returns {Promise<string>} A promise that resolves to the loaded content.
+     * @throws Error If the uid does not exist.
+     * @throws Error If the uid is not a valid string.
+     * @throws Error If the content is not a valid string.
+     * @throws Error If any other error occurs during loading.
      * @since 1.0.3
-     * @tutorial https://developers.signageos.io/docs/applets/api-guides/key-value-storage
+     * @tutorial https://developers.signageos.io/docs/sos-guides/key-value-storage
+     *
+     * @example
+     * // Previously saved content with uid 'ApplicationSecret'
+     * await sos.offline.cache.saveContent('ApplicationSecret', '123SuperSecretHash');
+     *
+     * // Load the content
+     * const content = await sos.offline.cache.loadContent('ApplicationSecret');
+     * console.log('Loaded content:', content); // Output: Loaded content: 123SuperSecretHash
      */
     loadContent(uid: string): Promise<string>;
     /**
-     * The `saveContent()` method saves a string value to the cache.
+     * The `saveContent()` method saves a string value to the cache with specified `uid`.
      *
+     * Use when you need to save some data into local memory. This API provides you with approach similar to the HTML5's Local Storage, but implemented internally via native device API and completely device-agnostic.
+     *
+     * @param uid Unique identifier of the content to be saved.
+     * @param content The string content to be saved.
+     * @returns {Promise<void>} A promise that resolves when the content is saved.
+     * @throws Error If the uid is not a valid string.
+     * @throws Error If the content is not a valid string.
+     * @throws Error If the uid already exists.
+     * @throws Error If any other error occurs during saving.
      * @since 1.0.3
-     * @tutorial https://developers.signageos.io/docs/applets/api-guides/key-value-storage
+     * @tutorial https://developers.signageos.io/docs/sos-guides/key-value-storage
+     *
+     * @example // {@link https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/offline-content | Example of Applet using saveContent()}
+     *
+     * @example
+     * sos.offline.cache.saveContent('ApplicationSecret', '123SuperSecretHash')
+     * .then(() => {
+     *     //Content was successfully saved, retrieve it.
+     *     return sos.offline.cache.loadContent('ApplicationSecret');
+     * })
+     * .then((content) => {
+     *     console.log('Loaded', content); // print 123SuperSecretHash
+     * })
      */
     saveContent(uid: string, content: string): Promise<void>;
     /**
-     * The `deleteContent() method removes the value specified by `uid` key.
+     * The `deleteContent()` method removes the value specified by `uid` key from the cache storage.
      *
+     * @param uid Unique identifier of the content to be deleted.
+     * @returns {Promise<void>} A promise that resolves when the content is deleted.
+     * @throws Error If the uid does not exist.
+     * @throws Error If the uid is not a valid string.
+     * @throws Error If any other error occurs during deletion.
      * @since 2.0.0
-     * @tutorial https://developers.signageos.io/docs/applets/api-guides/key-value-storage
+     * @tutorial https://developers.signageos.io/docs/sos-guides/key-value-storage
+     *
+     * @example
+     * //Store
+     * sos.offline.cache.saveContent('ApplicationSecret', '123SuperSecretHash')
+     * .then(() => {
+     *     //Content was successfully saved, retrieve it.
+     *     return sos.offline.cache.loadContent('ApplicationSecret');
+     * })
+     * .then((content) => {
+     *     console.log('Loaded', content); // print 123SuperSecretHash
+     *
+     *     // Let's delete the content now
+     *     return sos.offline.cache.deleteContent('ApplicationSecret')
+     * })
+     * .then(() => {
+     *     console.log("Deleted");
+     * })
+     * .catch((error) => { console.error(error); });
      */
     deleteContent(uid: string): Promise<void>;
     /**
      * The `validateChecksumFile()` method validates whether the file, specified by `uid`, has the correct checksum.
      *
-     * @throws If the uid does not exist or the hashing algorithm is not supported.
-     *
+     * @param uid Unique file identifier of a previously downloaded file.
+     * @param hash The expected checksum of the file.
+     * @param hashType The hashing algorithm to use. Supported algorithms are 'md5' and `crc32`.
+     * @returns {Promise<boolean>} A promise that resolves to `true` if the checksum is valid, otherwise `false`.
+     * @throws Error If the uid does not exist or the hashing algorithm is not supported.
+     * @throws Error If the hash is not a valid string.
+     * @throws Error If the hashType is not a valid string.
      * @since 2.0.0
+     *
+     * @example
+     * // Validate the checksum of a file
+     * const expectedHash = 'd41d8cd98f00b204e9800998ecf8427e'; // Example MD5 hash
+     * // Previously saved file with uid 'example-file.mp4'
+     * const isValid = await sos.offline.cache.validateChecksumFile('example-file.mp4', expectedHash, 'md5');
      */
     validateChecksumFile(uid: string, hash: string, hashType: HashAlgorithm): Promise<boolean>;
     /**
      * The `getChecksumFile()` computes a checksum of the file specified by `uid`.
      *
-     * @throws If the uid does not exist or the hashing algorithm is not supported.
-     *
+     * @param uid Unique file identifier of a previously downloaded file.
+     * @param hashType The hashing algorithm to use. Supported algorithms are `md5` and `crc32`.
+     * @returns {Promise<string>} A promise that resolves to the computed checksum of the file.
+     * @throws Error If the uid does not exist.
+     * @throws Error If the hashing algorithm is not supported.
      * @since 2.0.0
+     *
+     * @example // {@link https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/md5-checksum | Example Applet with MD5 Checksum}
+     *
+     * @example
+     * const checksum = await sos.offline.cache.getChecksumFile('example-file.mp4', 'md5');
+     * console.log('MD5 Checksum:', checksum); // Output: MD5 Checksum: d41d8cd98f00b204e9800998ecf8427e
      */
     getChecksumFile(uid: string, hashType: HashAlgorithm): Promise<string>;
     /**
      * The `decompressFile()` decompresses the file specified by `uid` into a new file specified by `destinationUid`.
      *
-     * @throws If the uid does not exist.
-     *
+     * @param uid Unique file identifier of a previously downloaded ZIP file.
+     * @param destinationUid Unique directory identifier (prefix of file) to extract ZIP file.
+     * @param method The decompression method to use. Currently, only 'zip' is supported.
+     * @returns {Promise<void>} A promise that resolves when the file is decompressed.
+     * @throws Error If the uid does not exist.
+     * @throws Error If the destinationUid is not a valid string.
+     * @throws Error If the method is not supported.
      * @since 2.1.0
+     *
+     * @example // {@link https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/offline-zip-decompress | Example Applet with Offline ZIP Decompression}
+     * @example
+     * // Save the ZIP file
+     * await sos.offline.cache.saveFile('example-zip-file.zip', 'https://example.com/path/to/your/file.zip');
+     *
+     * // Decompress the ZIP file into a directory
+     * await sos.offline.cache.decompressFile('example-zip-file.zip', 'extracted-files/', 'zip');
+     * 	.then(() => { console.log('ZIP file extracted'); })
+     * 	.catch((error) => { console.error(error); });
      */
     decompressFile(uid: string, destinationUid: string, method: 'zip'): Promise<void>;
     private getCachedFile;