Merge pull request #230 from AdobeXD/shotts/xd35docs

Changes for XD 35

Author: kerrishotts

SUMMARY.md

@@ -54,6 +54,9 @@
           * [WebSocket](./reference/uxp/class/WebSocket.md)
         * [Storage APIs](./reference/uxp/storage-index.md)
           * [Storage module](./reference/uxp/module/storage.md)
+          * [Local Storage](./reference/uxp/module/localStorage.md)
+          * [Session Storage](./reference/uxp/module/sessionStorage.md)
+          * [Secure Storage](./reference/uxp/module/secureStorage.md)
         * [Shell](./reference/uxp/class/Shell.md)
         * [OS](./reference/uxp/class/OS.md)
         * [UI APIs](./reference/uxp/ui-index.md)

reference/uxp/module/localStorage.md

@@ -0,0 +1,82 @@
+<a name="localstorage" id="localstorage"></a>
+
+# window.localStorage
+Provides a local key-value store useful for setting preferences and other kinds of data.
+This data is technically persistent, but can be cleared in a variety of ways, so you should not
+store data using `localStorage` that you cannot otherwise reconstruct.
+
+<InlineAlert variant="warning" slots="text"/>
+
+Do not store passwords or other secure forms of data using `localStorage`. Instead, use [secureStorage](./secureStorage.md).
+
+
+
+<a name="localstorage-length" id="localstorage-length"></a>
+
+## length ⇒ `int`
+**Read only**
+Returns number of items stored in the local storage.
+
+**Returns**: `int` - returns the number of items  
+
+
+<a name="localstorage-key" id="localstorage-key"></a>
+
+## key()
+Returns key which is stored at the given index
+
+**Returns**: `int` - Returns key which is stored at the given index.  
+
+| Param | Type |
+| --- | --- |
+| index. | `number` | 
+
+
+
+<a name="localstorage-getitem" id="localstorage-getitem"></a>
+
+## getItem(key)
+Get value from the local storage for the key.
+
+**Returns**: `string` - returns value corresponding to the key as string. If key doesn't exist, this function returns null.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| key | `string` | A key to get value. |
+
+
+
+<a name="localstorage-setitem" id="localstorage-setitem"></a>
+
+## setItem(key, value)
+Set key and value to the local storage.
+If the key is newly set or value is different from old value, an update event will be fired later.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| key | `string` | A key to set value |
+| value | `string` | A value for the key |
+
+
+
+<a name="localstorage-removeitem" id="localstorage-removeitem"></a>
+
+## removeItem(key)
+Remove a key/value pair from the local storage.
+If the key exists in the local storage, an update event will be fired later.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| key | `string` | A key to set value |
+
+
+
+<a name="localstorage-clear" id="localstorage-clear"></a>
+
+## clear()
+Remove all key/value pairs from the local storage.
+An update event will be fired later.
+
+

reference/uxp/module/secureStorage.md

@@ -0,0 +1,104 @@
+<a name="securestorage" id="securestorage"></a>
+
+# require('uxp').storage.secureStorage
+SecureStorage provides a protected storage which can be used to store sensitive data
+per plugin. SecureStorage takes a key-value pair and encrypts the value before being
+stored. After encryption, it stores the key and the encrypted value pair. When the value
+is requested with an associated key, it's retrieved after being decrypted. Please note
+that the key is not encrypted thus it's not protected by the cryptographic operation.
+
+Caveats for SecureStorage are as follows:
+1. SecureStorage is not an appropriate storage for sensitive data which wants to keep
+secret from the current user. SecureStorage is protected under the current user's
+account credential. It means the encrypted data can be at risk of being decrypted
+with the current user's privilege.
+2. Data in SecureStorage can be lost for various reasons. For an example, the user
+could uninstall the host application and delete the secure storage. Or, the cryptographic
+information used by the secure storage could be damaged by the user accidentally, and
+it will result in loss of data without the secure storage being removed. SecureStorage
+should be regarded as a cache rather than a persistent storage. Data in SecureStorage
+should be able to be regenerated from plugins after the time of loss.
+
+
+
+<a name="securestorage-length" id="securestorage-length"></a>
+
+## length ⇒ `int`
+**Read only**
+Returns number of items stored in the secure storage.
+
+**Returns**: `int` - returns the number of items  
+
+
+<a name="securestorage-setitem" id="securestorage-setitem"></a>
+
+## setItem(key, value)
+Store a key and value pair after the value is encrypted in a secure storage
+
+**Returns**: `Promise` - : resolved when the value is stored. rejected when the value is empty or not stored.  
+**Throws**:
+
+- `TypeError` : thrown when either key or value doesn't have one of acceptable types.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| key | `string` | : a key to set value |
+| value | `string` \| `ArrayBuffer` \| `TypedArray` | : a value for a key. |
+
+
+
+<a name="securestorage-getitem" id="securestorage-getitem"></a>
+
+## getItem(key)
+Retrieve a value associated with a provided key after the value is being decrypted from a secure storage.
+
+**Returns**: `Promise.<Uint8Array>` - : a value as buffer  
+**Throws**:
+
+- `TypeError` : thrown when a key doesn't have an acceptable type.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| key | `string` | : a key to get value |
+
+
+
+<a name="securestorage-removeitem" id="securestorage-removeitem"></a>
+
+## removeItem(key)
+Remove a value associated with a provided key
+
+**Returns**: `Promise` - : resolved when the value associated with the key is removed. rejected when the value is neither removed nor found.  
+**Throws**:
+
+- `TypeError` : thrown when a key doesn't have an acceptable type.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| key | `string` | : a key to remove value |
+
+
+
+<a name="securestorage-key" id="securestorage-key"></a>
+
+## key()
+Returns a key which is stored at the given index
+
+**Returns**: `int` - Returns the key which is stored at the given index.  
+
+| Param | Type |
+| --- | --- |
+| index. | `number` | 
+
+
+
+<a name="securestorage-clear" id="securestorage-clear"></a>
+
+## clear()
+Clear all values in a secure storage.
+
+**Returns**: `Promise` - : resolved when all the items are cleared. rejected when there is no item to clear or clear failed.  
+

reference/uxp/module/sessionStorage.md

@@ -0,0 +1,5 @@
+# window.sessionStorage
+
+Provides a local key/value store useful for storing data that persists only for the plugin's current session.
+
+For more information about the API itself, see the [localStorage](./localStorage.md) API.

reference/uxp/module/storage.md

@@ -39,6 +39,10 @@
         * [.getPluginFolder()](#module-storage-filesystemprovider-getpluginfolder) ⇒ `Promise.<Folder>`
         * [.getFsUrl(entry)](#module-storage-filesystemprovider-getfsurl) ⇒ `URL`
         * [.getNativePath(entry)](#module-storage-filesystemprovider-getnativepath) ⇒ `string`
+        * [.createSessionToken(entry)](#module-storage-filesystemprovider-createsessiontoken) ⇒ `string`
+        * [.getEntryForSessionToken(token)](#module-storage-filesystemprovider-getentryforsessiontoken) ⇒ `Entry`
+        * [.createPersistentToken(entry)](#module-storage-filesystemprovider-createpersistenttoken) ⇒ `Promise<string>`
+        * [.getEntryForPersistentToken(token)](#module-storage-filesystemprovider-getentryforpersistenttoken) ⇒ `Promise<Entry>`
     * [.Folder](#module-storage-folder) ⇐ `Entry`
         * [.getEntries()](#module-storage-folder-getentries) ⇒ `Promise.<Array.<Entry>>`
         * [.createFile(name, options)](#module-storage-folder-createfile) ⇒ `Promise.<File>`
@@ -638,6 +642,109 @@ Returns the platform native file system path of given entry.
 | --- | --- |
 | entry | `Entry` |
 
+<a name="module-storage-filesystemprovider-createsessiontoken" id="module-storage-filesystemprovider-createsessiontoken"></a>
+
+### createSessionToken(entry)
+Returns a token suitable for use with certain host-specific APIs. This
+token is valid only for the current plugin session. As such, it is of no use if you
+serialize the token to persistent storage, as the token will be invalid in the future.
+
+**Returns**: `string` - the session token for the given entry  
+
+| Param | Type |
+| --- | --- |
+| entry | `Entry` | 
+
+**Example**  
+```js
+const fs = require('uxp').storage.localFileSystem;
+let entry = await fs.getFileForOpening();
+let token = fs.createSessionToken(entry);
+```
+
+
+<a name="module-storage-filesystemprovider-getentryforsessiontoken" id="module-storage-filesystemprovider-getentryforsessiontoken"></a>
+
+### getEntryForSessionToken(token)
+Returns the file system Entry that corresponds to the session token obtained from
+`createSessionToken`. If an entry cannot be found that matches the token, then a
+`Reference Error: token is not defined` error is thrown.
+
+**Returns**: `Entry` - the corresponding entry for the session token  
+
+| Param | Type |
+| --- | --- |
+| token | `string` | 
+
+
+
+<a name="module-storage-filesystemprovider-createpersistenttoken" id="module-storage-filesystemprovider-createpersistenttoken"></a>
+
+### createPersistentToken(entry)
+Returns a token suitable for use with host-specific APIs (such as Xd), or
+for storing a persistent reference to an entry (useful if you want to only ask for
+permission to access a file or folder once). A persistent token is not guaranteed
+to last forever -- certain scenarios can cause the token to longer work (including
+moving files, changing permissions, or OS-specific limitations). If a persistent
+token cannot be reused, you'll get an error at the time of use.
+
+**Returns**: `string` - the persistent token for the given entry  
+
+| Param | Type |
+| --- | --- |
+| entry | `Entry` | 
+
+**Example**  
+```js
+const fs = require('uxp').storage.localFileSystem;
+let entry = await fs.getFileForOpening();
+let token = fs.createPersistentToken(entry);
+localStorage.setItem("persistent-file", token);
+```
+
+
+<a name="module-storage-filesystemprovider-getentryforpersistenttoken" id="module-storage-filesystemprovider-getentryforpersistenttoken"></a>
+
+### getEntryForPersistentToken(token)
+Returns the file system Entry that corresponds to the persistent token obtained from
+`createPersistentToken`. If an entry cannot be found that matches the token, then a
+`Reference Error: token is not defined` error is thrown.
+
+> Retrieving an entry for a persistent token does _not_ guarantee that the
+entry is valid for use. You'll need to properly handle the case where the entry no
+longer exists on the disk, or the permissions have changed by catching the appropriate
+errors. If that occurs, the suggested practice is to prompt the user for the entry
+again and store the new token.
+
+**Returns**: `Entry` - the corresponding entry for the persistent token  
+
+| Param | Type |
+| --- | --- |
+| token | `string` | 
+
+**Example**  
+```js
+const fs = require('uxp').storage.localFileSystem;
+let entry, contents, tries = 3, success = false;
+while (tries > 0) {
+    try {
+        entry = await fs.getEntryForPersistentToken(localStorage.getItem("persistent-file"));
+        contents = await entry.read();
+        tries = 0;
+        success = true;
+    } catch (err) {
+        entry = await fs.getFileForOpening();
+        localStorage.setItem("persistent-token", await fs.createPersistentToken(entry));
+        tries--;
+    }
+}
+if (!success) {
+    // fail gracefully somehow
+}
+```
+
+
+
 
 <a name="module-storage-folder" id="module-storage-folder"></a>