beaker-plugin-safe-app

0.1.0-dev.1

SAFE App

The safeApp API is the entry point to interact with the SAFE network

window.safeApp.initialise

src/api/app.js

Create a new SAFEApp instance without a connection to the network

window.safeApp.initialise(appInfo: AppInfo, safeAppGroupId: any, networkStateCallback: Function): Promise<SAFEAppHandle>
Parameters
appInfo (AppInfo)
safeAppGroupId (any)
networkStateCallback (Function = null) optional callback function to receive network state updates after a unregistered/registered connection is made with connect / connectAuthorised functions.
Returns
Promise<SAFEAppHandle>: new app instance handle
Example
window.safeApp.initialise({
      id: 'net.maidsafe.test.webapp.id',
      name: 'WebApp Test',
      vendor: 'MaidSafe Ltd.'
   }, (newState) => {
      console.log("Network state changed to: ", newState);
   })
   .then((appHandle) => {
      console.log('SAFEApp instance initialised and handle returned: ', appHandle);
   });

window.safeApp.connect

src/api/app.js

Create a new, unregistered session (read-only), e.g. useful for browsing web sites or just publicly available data.

window.safeApp.connect(appHandle: SAFEAppHandle): Promise<SAFEAppHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
Promise<SAFEAppHandle>: same app handle
Example
window.safeApp.initialise({
   id: 'net.maidsafe.test.webapp.id',
   name: 'WebApp Test',
   vendor: 'MaidSafe Ltd.'
})
.then((appHandle) => window.safeApp.connect(appHandle))
.then(_ => {
   console.log('Unregistered session created');
});

window.safeApp.authorise

src/api/app.js

Request the Authenticator (and user) to authorise this application with the given permissions and optional parameters.

window.safeApp.authorise(appHandle: SAFEAppHandle, permissions: Object, options: Object): Promise<AuthURI>
Parameters
appHandle (SAFEAppHandle) the app handle
permissions (Object) mapping the container-names to a list of permissions you want to request
options (Object) optional parameters
Name Description
options.own_container Boolean (default false) whether or not to request our own container to be created for the app.
Returns
Promise<AuthURI>: auth granted safe-:// -URI
Example
// Example of authorising an app:
window.safeApp.authorise(
   appHandle, // the app handle obtained when invoking `initialise`
   {
     _public: ['Insert'], // request to insert into `_public` container
     _other: ['Insert', 'Update'] // request to insert and update in `_other` container
   },
   {own_container: true} // and we want our own container, too
).then((authUri) => {
   console.log('App was authorised and auth URI received: ', authUri);
});

window.safeApp.connectAuthorised

src/api/app.js

Create a new, registered Session (read-write) If you have received a response URI (which you are allowed to store securely), you can directly get an authenticated app by using this helper function. Just provide said URI as the second value.

window.safeApp.connectAuthorised(appHandle: SAFEAppHandle, authUri: AuthURI): Promise<SAFEAppHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
authUri (AuthURI) granted auth URI
Returns
Promise<SAFEAppHandle>: same app handle
Example
// Example of creating a registered session:
window.safeApp.authorise(
   appHandle, // the app handle obtained when invoking `initialise`
   {
     _public: ['Insert'], // request to insert into `_public` container
     _other: ['Insert', 'Update'] // request to insert and update in `_other` container
   },
   {own_container: true} // and we want our own container, too
)
.then((authUri) => window.safeApp.connectAuthorised(appHandle, authUri))
.then(_ => {
   console.log('The app was authorised & a session was created with the network');
});

window.safeApp.authoriseContainer

src/api/app.js

Request the Authenticator (and user) to authorise this application with further continer permissions.

window.safeApp.authoriseContainer(appHandle: SAFEAppHandle, permissions: Object): Promise<AuthURI>
Parameters
appHandle (SAFEAppHandle) the app handle
permissions (Object) mapping container name to list of permissions
Returns
Promise<AuthURI>: auth granted safe-:// -URI
Example
// Requesting further container authorisation:
window.safeApp.authoriseContainer(
  appHandle, // the app handle obtained when invoking `initialise`
  { _publicNames: ['Update'] } // request to update into `_publicNames` container
).then((authUri) => {
   console.log('App was authorised and auth URI received: ', authUri);
});

window.safeApp.webFetch

src/api/app.js

Lookup a given safe://-URL in accordance with the convention and fetch the requested object.

window.safeApp.webFetch(appHandle: SAFEAppHandle, url: any, authUri: AuthURI): Promise<File>
Parameters
appHandle (SAFEAppHandle) the app handle
url (any)
authUri (AuthURI) granted auth URI
Returns
Promise<File>: the file object found for that URL
Example
// Retrieving a web page:
window.safeApp.webFetch(
  appHandle, // the app handle obtained when invoking `initialise`
  'safe://servicename.publicid' // the SAFE Network URL
)
.then((data) => {
   console.log('Web page content retrieved: ', data.toString());
});

window.safeApp.isRegistered

src/api/app.js

Whether or not this is a registered/authenticated session.

window.safeApp.isRegistered(appHandle: SAFEAppHandle): Boolean
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
Boolean: true if this is an authenticated session
Example
// Checking if app is registered:
window.safeApp.isRegistered(appHandle)
   .then((r) => console.log('Is app registered?: ', r));

window.safeApp.networkState

src/api/app.js

Current network connection state, e.g. Connected or Disconnected.

window.safeApp.networkState(appHandle: SAFEAppHandle): String
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
String: network state
Example
// Checking network connection state:
window.safeApp.networkState(appHandle)
   .then((s) => console.log('Current network state: ', s));

window.safeApp.canAccessContainer

src/api/app.js

Whether or not this session has specifc permission access of a given container.

window.safeApp.canAccessContainer(appHandle: SAFEAppHandle, name: String, permissions: (String | Array<String>)): Promise<Boolean>
Parameters
appHandle (SAFEAppHandle) the app handle
name (String) name of the container, e.g. _public
permissions ((String | Array<String>) = ['Read']) permissions to check for
Returns
Promise<Boolean>: true if this app can access the container with given permissions
Example
// Checking if the app has 'Read' permission for the '_public' container:
window.safeApp.canAccessContainer(appHandle, '_public', ['Read'])
   .then((r) => console.log('Has the app `Read` permission for `_public` container?: ', r));

window.safeApp.refreshContainersPermissions

src/api/app.js

Refresh permissions for accessible containers from the network. Useful when you just connected or received a response from the authenticator.

window.safeApp.refreshContainersPermissions(appHandle: SAFEAppHandle): Promise<SAFEAppHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
Promise<SAFEAppHandle>: same app handle when finished refreshing

window.safeApp.getContainersNames

src/api/app.js

Get the names of all containers found.

window.safeApp.getContainersNames(appHandle: SAFEAppHandle): Promise<Array<String>>
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
Promise<Array<String>>: list of containers names

window.safeApp.getHomeContainer

src/api/app.js

Get the MutableData for the apps own container generated by Authenticator

window.safeApp.getHomeContainer(appHandle: SAFEAppHandle): Promise<MutableDataHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
Promise<MutableDataHandle>: the handle for the MutableData behind it
Example
// Retrieve home container:
window.safeApp.getHomeContainer(appHandle)
   .then((mdHandle) => window.safeMutableData.getVersion(mdHandle))
   .then((v) => console.log('Home Container version: ', v));

window.safeApp.getContainer

src/api/app.js

Lookup and return the information necessary to access a container.

window.safeApp.getContainer(appHandle: SAFEAppHandle, name: String): Promise<MutableDataHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
name (String) name of the container, e.g. _public
Returns
Promise<MutableDataHandle>: the MutableData handle the handle for the MutableData behind it
Example
// Retrieve the '_public' container:
window.safeApp.canAccessContainer(appHandle, '_public', ['Read'])
   .then((r) => {
      if (r) {
         console.log('The app has `Read` permission for `_public` container');
         window.safeApp.getContainer(appHandle, '_public')
            .then((mdHandle) => window.safeMutableData.getVersion(mdHandle))
            .then((v) => console.log('`_public` Container version: ', v));
      }
   });

window.safeApp.free

src/api/app.js

Free the SAFEApp instance from memory, as well as all other objects created with it, e.g. ImmutableData and MutableData objects, etc.

window.safeApp.free(appHandle: SAFEAppHandle)
Parameters
appHandle (SAFEAppHandle) the app handle

Immutable Data

The safeImmutableData API allows you to create and manipulate Immutable Data objects in the SAFE network

window.safeImmutableData.create

src/api/immutable_data.js

Create a new ImmutableData Writer

window.safeImmutableData.create(appHandle: SAFEAppHandle): Promise<WriterHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
Promise<WriterHandle>: the ImmutableData Writer handle
Example
// Creating a new ImmutableData writer:
window.safeImmutableData.create(appHandle)
   .then((idWriterHandle) => console.log('ImmutableData writer handle: ', idWriterHandle));

window.safeImmutableData.fetch

src/api/immutable_data.js

Look up an existing ImmutableData for the given address

window.safeImmutableData.fetch(appHandle: SAFEAppHandle, address: Buffer): Promise<ReaderHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
address (Buffer) the XorName on the network
Returns
Promise<ReaderHandle>: the ImmutableData Reader handle
Example
// Fetch an exisiting ImmutableData from the network:
window.safeImmutableData.create(appHandle)
   .then((idWriterHandle) => window.safeCipherOpt.newPlainText(appHandle)
     .then((cipherOptHandle) => window.safeImmutableData.closeWriter(idWriterHandle, cipherOptHandle))
   )
   .then((addr) => window.safeImmutableData.fetch(appHandle, addr))
   .then((idReaderHandle) => console.log('ImmutableData reader handle: ', idReaderHandle));

window.safeImmutableData.write

src/api/immutable_data.js

Append the given data to an ImmutableData.

window.safeImmutableData.write(writerHandle: WriterHandle, string: String): Promise
Parameters
writerHandle (WriterHandle) the ImmutableData Writer handle
string (String) the data to append
Returns
Promise: resolves when finished appending
Example
// Write data into an ImmutableData:
window.safeImmutableData.create(appHandle)
   .then((idWriterHandle) => window.safeImmutableData.write(idWriterHandle, 'my immutable data')
      .then(_ => window.safeCipherOpt.newPlainText(appHandle)
         .then((cipherOptHandle) => window.safeImmutableData.closeWriter(idWriterHandle, cipherOptHandle))
      )
      .then((addr) => console.log('ImmutableData written in the network at: ', addr))
   );

window.safeImmutableData.closeWriter

src/api/immutable_data.js

Close and write the ImmutableData to the network. Note this operation will free the ImmutableData Writer from the memory after the data is written in the network. Thus, a new Writer instance shall be created if more writing operations into the ImmutableData are required.

window.safeImmutableData.closeWriter(writerHandle: WriterHandle, cipherOptHandle: CipherOptHandle): Promise<String>
Parameters
writerHandle (WriterHandle) the ImmutableData Writer handle
cipherOptHandle (CipherOptHandle) the handle of the CipherOpt to use for encryption
Returns
Promise<String>: the address to the data once written to the network
Example
// Creating an ImmutableData and closing its writer to commit it to the network:
window.safeImmutableData.create(appHandle)
   .then((idWriterHandle) => window.safeCipherOpt.newPlainText(appHandle)
     .then((cipherOptHandle) => window.safeImmutableData.closeWriter(idWriterHandle, cipherOptHandle))
     .then((addr) => console.log('ImmutableData was stored at address: ', addr))
   );

window.safeImmutableData.read

src/api/immutable_data.js

Read the given amount of bytes from the network

window.safeImmutableData.read(readerHandle: ReaderHandle, options: Object?): Promise<String>
Parameters
readerHandle (ReaderHandle) the ImmutableData Reader handle
options (Object?) reading options
Name Description
options.offset Number (default 0) start position
options.end Number (default size) end position or end of data
Returns
Promise<String>: the data read
Example
// Read data from an ImmutableData:
window.safeImmutableData.create(appHandle)
   .then((idWriterHandle) => window.safeImmutableData.write(idWriterHandle, 'my immutable data')
      .then(_ => window.safeCipherOpt.newPlainText(appHandle)
         .then((cipherOptHandle) => window.safeImmutableData.closeWriter(idWriterHandle, cipherOptHandle))
      )
   )
   .then((addr) => window.safeImmutableData.fetch(appHandle, addr))
   .then((idReaderHandle) => window.safeImmutableData.read(idReaderHandle))
   .then((data) => console.log('ImmutableData data read: ', data.toString()));

window.safeImmutableData.size

src/api/immutable_data.js

The size of the mutable data on the network

window.safeImmutableData.size(readerHandle: ReaderHandle): Promise<Number>
Parameters
readerHandle (ReaderHandle) the ImmutableData Reader handle
Returns
Promise<Number>: length in bytes
Example
// Get the size of an ImmutableData:
window.safeImmutableData.create(appHandle)
   .then((idWriterHandle) => window.safeImmutableData.write(idWriterHandle, 'my immutable data')
      .then(_ => window.safeCipherOpt.newPlainText(appHandle)
         .then((cipherOptHandle) => window.safeImmutableData.closeWriter(idWriterHandle, cipherOptHandle))
      )
   )
   .then((addr) => window.safeImmutableData.fetch(appHandle, addr))
   .then((idReaderHandle) => window.safeImmutableData.size(idReaderHandle))
   .then((size) => console.log('Size of the ImmutableData: ', size));

window.safeImmutableData.free

src/api/immutable_data.js

Free the ImmutableData Reader instance from memory

window.safeImmutableData.free(readerHandle: ReaderHandle)
Parameters
readerHandle (ReaderHandle) the ImmutableData Reader handle

Mutable Data

The safeMutableData API allows you to create and manipulate Mutable Data objects in the SAFE network

window.safeMutableData.newRandomPrivate

src/api/mutable_data.js

Create a new mutuable data at a random address with private access.

window.safeMutableData.newRandomPrivate(appHandle: SAFEAppHandle, typeTag: Number): Promise<MutableDataHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
typeTag (Number) the typeTag to use
Returns
Promise<MutableDataHandle>: the MutableData handle
Example
// Create a PrivateMutable Data with random address:
window.safeMutableData.newRandomPrivate(appHandle, 15001)
   .then((mdHandle) => window.safeMutableData.getNameAndTag(mdHandle))
   .then((r) => console.log('New Private MutableData created with tag: ', r.tag, ' and name: ', r.name.buffer));

window.safeMutableData.newRandomPublic

src/api/mutable_data.js

Create a new mutuable data at a random address with public access.

window.safeMutableData.newRandomPublic(appHandle: SAFEAppHandle, typeTag: Number): Promise<MutableDataHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
typeTag (Number) the typeTag to use
Returns
Promise<MutableDataHandle>: the MutableData handle
Example
// Create a PublicMutable Data with random address:
window.safeMutableData.newRandomPublic(appHandle, 15001)
   .then((mdHandle) => window.safeMutableData.getNameAndTag(mdHandle))
   .then((r) => console.log('New Public MutableData created with tag: ', r.tag, ' and name: ', r.name.buffer));

window.safeMutableData.newPrivate

src/api/mutable_data.js

Initiate a mutuable data at the given address with private access. Note that the nonce can be generated with window.safeCrypto.generateNonce() function.

window.safeMutableData.newPrivate(appHandle: SAFEAppHandle, name: (String | Buffer), typeTag: Number, secKey: Number, nonce: Number): Promise<MutableDataHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
name ((String | Buffer)) Xor name/address of the MutbleData
typeTag (Number) the typeTag to use
secKey (Number) the secret encryption key to use
nonce (Number) the nonce
Returns
Promise<MutableDataHandle>: the MutableData handle
Example
// Create a PrivateMutable Data with specific address:
let name = 'name-private-0101010101010101010';
let secKey = 'secret-key-010101010101010101010';
window.safeCrypto.generateNonce()
   .then((nonce) => window.safeMutableData.newPrivate(appHandle, name, 15001, secKey, nonce))
   .then((mdHandle) => window.safeMutableData.getNameAndTag(mdHandle))
   .then((r) => console.log('New Private MutableData created with tag: ', r.tag, ' and name: ', r.name.buffer));

window.safeMutableData.newPublic

src/api/mutable_data.js

Initiate a mutuable data at the given address with public access.

window.safeMutableData.newPublic(appHandle: SAFEAppHandle, name: (String | Buffer), typeTag: Number): Promise<MutableDataHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
name ((String | Buffer)) Xor name/address of the MutbleData
typeTag (Number) the typeTag to use
Returns
Promise<MutableDataHandle>: the MutableData handle
Example
// Create a Public MutableData with specific address:
window.safeMutableData.newPublic(appHandle, 'name-private-0101010101010101010', 15001)
   .then((mdHandle) => window.safeMutableData.getNameAndTag(mdHandle))
   .then((r) => console.log('New Public MutableData created with tag: ', r.tag, ' and name: ', r.name.buffer));

window.safeMutableData.newPermissions

src/api/mutable_data.js

Create a new Permissions object.

window.safeMutableData.newPermissions(appHandle: SAFEAppHandle): Promise<PermissionsHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
Promise<PermissionsHandle>: the Permissions handle
Example
window.safeMutableData.newPermissions(appHandle)
   .then((permsHandle) => console.log('New Permissions created but not committed'));

window.safeMutableData.newPermissionSet

src/api/mutable_data.js

Create a new PermissionsSet object.

window.safeMutableData.newPermissionSet(appHandle: SAFEAppHandle): Promise<PermissionsSetHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
Promise<PermissionsSetHandle>: the PermissionsSet handle
Example
window.safeMutableData.newPermissionSet(appHandle)
   .then((permSetHandle) => console.log('New PermissionsSet created but not committed'));

window.safeMutableData.newMutation

src/api/mutable_data.js

Create a new Mutation object.

window.safeMutableData.newMutation(appHandle: SAFEAppHandle): Promise<MutationHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
Promise<MutationHandle>: the Mutation handle
Example
window.safeMutableData.newMutation(appHandle)
   .then((mutationHandle) => console.log('New Mutation created but not committed'));

window.safeMutableData.newEntries

src/api/mutable_data.js

Create a new Entries object.

window.safeMutableData.newEntries(appHandle: SAFEAppHandle): Promise<EntriesHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
Promise<EntriesHandle>: the Entries handle
Example
window.safeMutableData.newEntries(appHandle)
   .then((entriesHandle) => console.log('New Entries container created but not committed'));

window.safeMutableData.quickSetup

src/api/mutable_data.js

Set up a newly (not yet committed/created) MutableData with the app having full-access permissions (and no other).

window.safeMutableData.quickSetup(mdHandle: MutableDataHandle, data: Object): Promise<MutableDataHandle>
Parameters
mdHandle (MutableDataHandle) the MutableData handle
data (Object) a key-value payload it should create the data with
Returns
Promise<MutableDataHandle>: the same MutableData handle
Example
// Create a MutableData and set up its permissions automatically:
window.safeMutableData.newPublic(appHandle, 15001)
   .then((mdHandle) => window.safeMutableData.quickSetup(mdHandle, {key1: 'value1'}))
   .then((r) => console.log('New MutableData created and setup'));

window.safeMutableData.encryptKey

src/api/mutable_data.js

Encrypt the entry key provided as parameter with the encryption key contained in a Private MutableData. If the MutableData is Public, the same (and unencrypted) value is returned.

window.safeMutableData.encryptKey(mdHandle: MutableDataHandle, key: (String | Buffer)): Promise<Key>
Parameters
mdHandle (MutableDataHandle) the MutableData handle
key ((String | Buffer)) the key you want to encrypt
Returns
Promise<Key>: the encrypted entry key
Example
// Encrypt an entry's key using Private MutableData's encryption key:
window.safeMutableData.encryptKey(mdHandle, 'key1')
   .then((encryptedKey) => console.log('Encrypted key: ', encryptedKey));

window.safeMutableData.encryptValue

src/api/mutable_data.js

Encrypt the entry value provided as parameter with the encryption key contained in a Private MutableData. If the MutableData is Public, the same (and unencrypted) value is returned.

window.safeMutableData.encryptValue(mdHandle: MutableDataHandle, value: (String | Buffer)): Promise<Value>
Parameters
mdHandle (MutableDataHandle) the MutableData handle
value ((String | Buffer)) the data you want to encrypt
Returns
Promise<Value>: the encrypted entry value
Example
// Encrypt an entry's value using Private MutableData's encryption key:
window.safeMutableData.encryptValue(mdHandle, 'value1')
   .then((encryptedValue) => console.log('Encrypted value: ', encryptedValue));

window.safeMutableData.decrypt

src/api/mutable_data.js

Decrypt the entry key/value provided as parameter with the encryption key contained in a Private MutableData.

window.safeMutableData.decrypt(mdHandle: MutableDataHandle, value: (String | Buffer)): Promise<Value>
Parameters
mdHandle (MutableDataHandle) the MutableData handle
value ((String | Buffer)) the data you want to decrypt
Returns
Promise<Value>: the decrypted value
Example
// Encrypt and decrypt an entry's key/value using Private MutableData's encryption key:
let encryptedKey, encryptedValue;
window.safeMutableData.encryptKey(mdHandle, 'key1')
   .then((cipher) => encryptedKey = cipher)
   .then(_ => window.safeMutableData.encryptValue(mdHandle, 'value1'))
   .then((cipher) => encryptedValue = cipher)
   .then(_ => window.safeMutableData.decrypt(mdHandle, encryptedKey))
   .then((decryptedKey) => console.log('Decrypted key: ', decryptedKey.toString()))
   .then(_ => window.safeMutableData.decrypt(mdHandle, encryptedValue))
   .then((decryptedValue) => console.log('Decrypted value: ', decryptedValue.toString()));

window.safeMutableData.getNameAndTag

src/api/mutable_data.js

Look up the name and tag of the MutableData as required to look it up on the network.

window.safeMutableData.getNameAndTag(mdHandle: MutableDataHandle): Promise<NameAndTag>
Parameters
mdHandle (MutableDataHandle) the MutableData handle
Returns
Promise<NameAndTag>: the name and tag values
Example
// Retrieveing the name and tag of a MutableData:
window.safeMutableData.getNameAndTag(mdHandle)
 .then((res) => {
    console.log('Name: ', res.name.buffer);
    console.log('Tag: ', res.tag);
 });

window.safeMutableData.getVersion

src/api/mutable_data.js

Look up the MutableData object version on the network

window.safeMutableData.getVersion(mdHandle: MutableDataHandle): Promise<Number>
Parameters
mdHandle (MutableDataHandle) the MutableData handle
Returns
Promise<Number>: current version
Example
// Retrieveing the version of a MutableData:
window.safeMutableData.getVersion(mdHandle)
 .then((version) => console.log('MutableData current version: ', version));

window.safeMutableData.get

src/api/mutable_data.js

Look up the value of a specific key

window.safeMutableData.get(mdHandle: MutableDataHandle, key: String): Promise<ValueVersion>
Parameters
mdHandle (MutableDataHandle) the MutableData handle
key (String) the entry's key
Returns
Promise<ValueVersion>: the value at the current version
Example
// Retrieveing the value of an entry:
window.safeMutableData.newPublic(appHandle, 15001)
   .then((mdHandle) => window.safeMutableData.quickSetup(mdHandle, {key1: 'value1'})
      .then(_ => window.safeMutableData.get(mdHandle, 'key1'))
      .then((value) => {
         console.log('Value: ', value.buf.toString());
         console.log('Version: ', value.version);
      })
   );

window.safeMutableData.put

src/api/mutable_data.js

Create/commit this MutableData on the network.

window.safeMutableData.put(mdHandle: MutableDataHandle, permissionsHandle: (PermissionsHandle | null), entriesHandle: (EntriesHandle | null)): Promise
Parameters
mdHandle (MutableDataHandle) the MutableData handle
permissionsHandle ((PermissionsHandle | null)) the permissions to create the MutableData with
entriesHandle ((EntriesHandle | null)) data payload to create the MutableData with
Returns
Promise: it resolves when finished creating it
Example
// Committing a MutableData to the network:
let mdHandle, entriesHandle, pmSetHandle, appSignKeyHandle, permissionsHandle;
window.safeMutableData.newEntries(appHandle)
   .then((h) => entriesHandle = h)
   .then(_ => window.safeMutableDataEntries.insert(entriesHandle, 'key1', 'value1'))
   .then(_ => window.safeCrypto.getAppPubSignKey(appHandle))
   .then((pk) => appSignKeyHandle = pk)
   .then(_ => window.safeMutableData.newPermissionSet(appHandle))
   .then((h) => pmSetHandle = h)
   .then(_ => window.safeMutableDataPermissionsSet.setAllow(pmSetHandle, 'Insert'))
   .then(_ => window.safeMutableDataPermissionsSet.setAllow(pmSetHandle, 'ManagePermissions'))
   .then(_ => window.safeMutableData.newPermissions(appHandle))
   .then((h) => permissionsHandle = h)
   .then(_ => window.safeMutableDataPermissions.insertPermissionsSet(permissionsHandle, appSignKeyHandle, pmSetHandle))
   .then(_ => window.safeMutableData.newRandomPublic(appHandle, 15000))
   .then((h) => mdHandle = h)
   .then(_ => console.log('Finished preparation'))
   .then(_ => window.safeMutableData.put(mdHandle, permissionsHandle, entriesHandle))
   .then(_ => console.log('Finished creating and committing MutableData to the network'));

window.safeMutableData.getEntries

src/api/mutable_data.js

Get a handle to the entries associated with this MutableData

window.safeMutableData.getEntries(mdHandle: MutableDataHandle): Promise<EntriesHandle>
Parameters
mdHandle (MutableDataHandle) the MutableData handle
Returns
Promise<EntriesHandle>: the Entries handle
Example
// Retrieving the entries:
window.safeMutableData.getEntries(mdHandle)
   .then((entriesHandle) => window.safeMutableDataEntries.len(entriesHandle))
   .then((len) => console.log('Number of entries in the MutableData: ', len));

window.safeMutableData.getKeys

src/api/mutable_data.js

Get a handle to the keys associated with this MutableData

window.safeMutableData.getKeys(mdHandle: MutableDataHandle): Promise<KeysHandle>
Parameters
mdHandle (MutableDataHandle) the MutableData handle
Returns
Promise<KeysHandle>: the Keys handle
Example
// Retrieving the keys:
window.safeMutableData.getKeys(mdHandle)
   .then((keysHandle) => window.safeMutableDataKeys.len(keysHandle))
   .then((len) => console.log('Number of keys in the MutableData: ', len));

window.safeMutableData.getValues

src/api/mutable_data.js

Get a handle to the values associated with this MutableData

window.safeMutableData.getValues(mdHandle: MutableDataHandle): Promise<ValuesHandle>
Parameters
mdHandle (MutableDataHandle) the MutableData handle
Returns
Promise<ValuesHandle>: the Values handle
Example
// Retrieving the values:
window.safeMutableData.getValues(mdHandle)
   .then((valuesHandle) => window.safeMutableDataValues.len(valuesHandle))
   .then((len) => console.log('Number of values in the MutableData: ', len));

window.safeMutableData.getPermissions

src/api/mutable_data.js

Get a handle to the permissions associated with this MutableData

window.safeMutableData.getPermissions(mdHandle: MutableDataHandle): Promise<PermissionsHandle>
Parameters
mdHandle (MutableDataHandle) the MutableData handle
Returns
Promise<PermissionsHandle>: the Permissions handle
Example
// Retrieving the permissions:
window.safeMutableData.getPermissions(mdHandle)
   .then((permsHandle) => window.safeMutableDataPermissions.len(permsHandle))
   .then((len) => console.log('Number of permissions in the MutableData: ', len));

window.safeMutableData.getUserPermissions

src/api/mutable_data.js

Get a handle to the permissions associated with this MutbleData for a specifc key. If the SignKeyHandle provided is null it will be then assummed as USER_ANYONE.

window.safeMutableData.getUserPermissions(mdHandle: MutableDataHandle, signKeyHandle: (SignKeyHandle | null)): Promise<PermissionsSetHandle>
Parameters
mdHandle (MutableDataHandle) the MutableData handle
signKeyHandle ((SignKeyHandle | null)) the sign key to look up
Returns
Promise<PermissionsSetHandle>: the PermissionsSet handle
Example
// Retrieving the permissions set associated to a sign key:
window.safeMutableData.getUserPermissions(mdHandle, signKey)
   .then((permSetHandle) => console.log('PermissionsSet retrieved'));

window.safeMutableData.delUserPermissions

src/api/mutable_data.js

Delete the permissions of a specifc key. Directly commits to the network. Requires 'ManagePermissions' permission for the app. If the SignKeyHandle provided is null it will be then assummed as USER_ANYONE.

window.safeMutableData.delUserPermissions(mdHandle: MutableDataHandle, signKeyHandle: (SignKeyHandle | null), version: Number): Promise
Parameters
mdHandle (MutableDataHandle) the MutableData handle
signKeyHandle ((SignKeyHandle | null)) the sign key to lookup for
version (Number) the version successor, to confirm you are actually asking for the right state
Returns
Promise: resolves when finished
Example
// Remove the permissions set associated to a sign key:
window.safeMutableData.getVersion(mdHandle)
   .then((version) => window.safeMutableData.delUserPermissions(mdHandle, signKey, version + 1))
   .then(_ => console.log('PermissionsSet removed for the sign key provided'));

window.safeMutableData.setUserPermissions

src/api/mutable_data.js

Set the permissions of a specifc key. Directly commits to the network. Requires 'ManagePermissions' permission for the app. If the SignKeyHandle provided is null the permission set will be then set for USER_ANYONE.

window.safeMutableData.setUserPermissions(mdHandle: MutableDataHandle, signKeyHandle: (SignKeyHandle | null), pmSetHandle: PermissionsSetHandle, version: Number): Promise
Parameters
mdHandle (MutableDataHandle) the MutableData handle
signKeyHandle ((SignKeyHandle | null)) the sign key to lookup for
pmSetHandle (PermissionsSetHandle) the PermissionsSet to set to
version (Number) the version successor, to confirm you are actually asking for the right state
Returns
Promise: resolves when finished
Example
// Setting a new permission into a MutableData:
let pmSetHandle, appSignKeyHandle;
window.safeCrypto.getAppPubSignKey(appHandle)
   .then((pk) => appSignKeyHandle = pk)
   .then(_ => window.safeMutableData.newPermissionSet(appHandle))
   .then((h) => pmSetHandle = h)
   .then(_ => window.safeMutableDataPermissionsSet.setAllow(pmSetHandle, 'Delete'))
   .then(_ => window.safeMutableData.getVersion(mdHandle))
   .then((version) => window.safeMutableData.setUserPermissions(mdHandle, appSignKeyHandle, pmSetHandle, version + 1))
   .then(_ => console.log('Finished setting user permission'));

window.safeMutableData.applyEntriesMutation

src/api/mutable_data.js

Commit the mutations transaction to the network

window.safeMutableData.applyEntriesMutation(mdHandle: MutableDataHandle, mutationHandle: MutationHandle): Promise
Parameters
mdHandle (MutableDataHandle) the MutableData handle
mutationHandle (MutationHandle) the Mutation you want to apply
Returns
Promise: resolves when finished
Example
// Apply an insert mutation to a MutableData:
let mutationHandle;
window.safeMutableData.newMutation(mdHandle)
   .then((h) => mutationHandle = h)
   .then(_ => window.safeMutableDataMutation.insert(mutationHandle, 'key1', 'value1'))
   .then(_ => window.safeMutableData.applyEntriesMutation(mdHandle, mutationHandle))
   .then(_ => console.log('New entry was inserted in the MutableData and committed to the network'));

window.safeMutableData.serialise

src/api/mutable_data.js

Serialise the current MutableData

window.safeMutableData.serialise(mdHandle: MutableDataHandle): Promise<String>
Parameters
mdHandle (MutableDataHandle) the MutableData handle
Returns
Promise<String>: the serialised MutableData
Example
// Get the serialised version of a MutableData:
window.safeMutableData.serialise(mdHandle)
   .then((serial) => console.log('MutbleData serialised version retrieved: ', serial));

window.safeMutableData.fromSerial

src/api/mutable_data.js

Deserialize the MutableData

window.safeMutableData.fromSerial(appHandle: SAFEAppHandle, data: String): Promise<MutableDataHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
data (String) the serialised MutableData
Returns
Promise<MutableDataHandle>: the MutableData handle
Example
// Access MutableData information from its serialised version:
window.safeMutableData.serialise(mdHandle)
   .then((serial) => window.safeMutableData.fromSerial(appHandle, serial))
      .then((mdHdl) => window.safeMutableData.get(mdHdl, 'key1'))
      .then((value) => {
         console.log('Value: ', value.buf.toString());
         console.log('Version: ', value.version);
      });

window.safeMutableData.emulateAs

src/api/mutable_data.js

Wrap this MutableData into a known abstraction. Currently known: NFS

window.safeMutableData.emulateAs(mdHandle: MutableDataHandle, eml: String): NFSHandle
Parameters
mdHandle (MutableDataHandle) the MutableData handle
eml (String) name of the emulation
Returns
NFSHandle: the NFS emulation you are asking for
Example
// Access a MutableData using NFS emulation:
window.safeMutableData.emulateAs(mdHandle, 'NFS')
   .then((nfsHandle) => window.safeNfs.fetch(nfsHandle, 'file.txt'))
   .then((idHdl) => console.log('ImmutableData behind `file.txt` fetched'));

window.safeMutableData.free

src/api/mutable_data.js

Free the MutableData instance from memory

window.safeMutableData.free(mdHandle: String)
Parameters
mdHandle (String) the MutableData handle

Mutable Data Entries

The safeMutableDataEntries API allows you to manipulate the entries of a Mutable Data object in the SAFE network

window.safeMutableDataEntries.len

src/api/mutable_data_entries.js

Get the total number of entries in the MutableData

window.safeMutableDataEntries.len(entriesHandle: EntriesHandle): Promise<Number>
Parameters
entriesHandle (EntriesHandle) the Entries handle
Returns
Promise<Number>: number of entries
Example
// Retrieving the number of entries:
window.safeMutableData.getEntries(mdHandle)
   .then((entriesHandle) => window.safeMutableDataEntries.len(entriesHandle))
   .then((len) => console.log('Number of entries in the MutableData: ', len));

window.safeMutableDataEntries.get

src/api/mutable_data_entries.js

Look up the value of a specific key

window.safeMutableDataEntries.get(entriesHandle: EntriesHandle, keyName: String): Promise<ValueVersion>
Parameters
entriesHandle (EntriesHandle) the Entries handle
keyName (String) the entry's key
Returns
Promise<ValueVersion>: the current version
Example
// Retrieving a value:
window.safeMutableData.getEntries(mdHandle)
   .then((entriesHandle) => window.safeMutableDataEntries.get(entriesHandle, 'key1'))
   .then((value) => {
      console.log('Value: ', value.buf.toString());
      console.log('Version: ', value.version);
   });

window.safeMutableDataEntries.forEach

src/api/mutable_data_entries.js

Iterate over the entries, execute the function every time

window.safeMutableDataEntries.forEach(entriesHandle: EntriesHandle, fn: function (Buffer, ValueVersion)): Promise
Parameters
entriesHandle (EntriesHandle) the Entries handle
fn (function (Buffer, ValueVersion)) the function to call
Returns
Promise: resolves once the iteration is done
Example
// Iterating over the entries of a MutableData:
window.safeMutableData.getEntries(mdHandle)
   .then((entriesHandle) => window.safeMutableDataEntries.forEach(entriesHandle, (k, v) => {
         console.log('Key: ', k.toString());
         console.log('Value: ', v.buf.toString());
         console.log('Version: ', v.version);
      }).then(_ => console.log('Iteration finished'))
   );

window.safeMutableDataEntries.insert

src/api/mutable_data_entries.js

Insert a new entry. Will directly commit that transaction to the network. Will fail if the entry already exists or the current app doesn't have the permissions to edit that MutableData.

window.safeMutableDataEntries.insert(entriesHandle: EntriesHandle, keyName: (String | Buffer), value: (String | Buffer)): Promise
Parameters
entriesHandle (EntriesHandle) the Entries handle
keyName ((String | Buffer)) the key you want store the data under
value ((String | Buffer)) the data you want to store
Returns
Promise: resolves when finished
Example
// Inserting an entry:
window.safeMutableData.getEntries(mdHandle)
   .then((entriesHandle) => window.safeMutableDataEntries.insert(entriesHandle, 'key1', 'value1'))
   .then(_ => console.log('New entry inserted');

window.safeMutableDataEntries.mutate

src/api/mutable_data_entries.js

Start a new transaction of mutation of the entries

window.safeMutableDataEntries.mutate(entriesHandle: EntriesHandle): Promise<MutationHandle>
Parameters
entriesHandle (EntriesHandle) the Entries handle
Returns
Promise<MutationHandle>: the Mutation handle
Example
// Mutate current entries by inserting a new entry:
let mutationHandle;
window.safeMutableData.getEntries(mdHandle)
   .then((entriesHandle) => window.safeMutableDataEntries.mutate(entriesHandle))
   .then((h) => mutationHandle = h)
   .then(_ => window.safeMutableDataMutation.insert(mutationHandle, 'key1', 'value1'))
   .then(_ => window.safeMutableData.applyEntriesMutation(mdHandle, mutationHandle))
   .then(_ => console.log('New entry was inserted in the MutableData and committed to the network'));

window.safeMutableDataEntries.free

src/api/mutable_data_entries.js

Free the Entries instance from memory

window.safeMutableDataEntries.free(entriesHandle: String)
Parameters
entriesHandle (String) the Entries handle

Mutable Data Keys

The safeMutableDataKeys API allows you to manipulate the keys of a Mutable Data object in the SAFE network

window.safeMutableDataKeys.len

src/api/mutable_data_keys.js

Get the total number of keys in the MutableData

window.safeMutableDataKeys.len(keysHandle: KeysHandle): Promise<Number>
Parameters
keysHandle (KeysHandle) the Keys handle
Returns
Promise<Number>: the number of keys
Example
// Retrieving the number of keys:
window.safeMutableData.getKeys(mdHandle)
   .then((keysHandle) => window.safeMutableDataKeys.len(keysHandle))
   .then((len) => console.log('Number of keys in the MutableData: ', len));

window.safeMutableDataKeys.forEach

src/api/mutable_data_keys.js

Iterate over the keys, execute the function every time

window.safeMutableDataKeys.forEach(keysHandle: KeysHandle, fn: function (Buffer)): Promise
Parameters
keysHandle (KeysHandle) the Keys handle
fn (function (Buffer)) the function to call with the key in the buffer
Returns
Promise: resolves once the iteration is done
Example
// Iterating over the keys of a MutableData:
window.safeMutableData.getKeys(mdHandle)
   .then((keysHandle) => window.safeMutableDataKeys.forEach(keysHandle, (k) => {
         console.log('Key: ', k.toString());
      }).then(_ => console.log('Iteration finished'))
   );

window.safeMutableDataKeys.free

src/api/mutable_data_keys.js

Free the Keys instance from memory

window.safeMutableDataKeys.free(keysHandle: String)
Parameters
keysHandle (String) the Keys handle

Mutable Data Values

The safeMutableDataValues API allows you to manipulate the values of a Mutable Data object in the SAFE network

window.safeMutableDataValues.len

src/api/mutable_data_values.js

Get the total number of values in the MutableData

window.safeMutableDataValues.len(valuesHandle: ValuesHandle): Promise<Number>
Parameters
valuesHandle (ValuesHandle) the Values handle
Returns
Promise<Number>: the number of values
Example
// Retrieving the number of values:
window.safeMutableData.getValues(mdHandle)
   .then((valuesHandle) => window.safeMutableDataValues.len(valuesHandle))
   .then((len) => console.log('Number of values in the MutableData: ', len));

window.safeMutableDataValues.forEach

src/api/mutable_data_values.js

Iterate over the values, execute the function every time

window.safeMutableDataValues.forEach(valuesHandle: ValuesHandle, fn: function (Buffer, ValueVersion)): Promise
Parameters
valuesHandle (ValuesHandle) the Values handle
fn (function (Buffer, ValueVersion)) the function to call
Returns
Promise: resolves once the iteration finished
Example
// Iterating over the values of a MutableData:
window.safeMutableData.getValues(mdHandle)
   .then((valuesHandle) => window.safeMutableDataValues.forEach(valuesHandle, (v) => {
         console.log('Value: ', v.buf.toString());
         console.log('Version: ', v.version);
      }).then(_ => console.log('Iteration finished'))
   );

window.safeMutableDataValues.free

src/api/mutable_data_values.js

Free the Values instance from memory

window.safeMutableDataValues.free(valuesHandle: String)
Parameters
valuesHandle (String) the Values handle

Mutable Data Mutation

The safeMutableDataMutation API allows you to manipulate and apply Mutations on a Mutable Data object in the SAFE network

window.safeMutableDataMutation.insert

src/api/mutable_data_mutation.js

Store a new Insert-action in the transaction.

window.safeMutableDataMutation.insert(mutationHandle: MutationHandle, keyName: (String | Buffer), value: (String | Buffer)): Promise
Parameters
mutationHandle (MutationHandle) the Mutation handle
keyName ((String | Buffer))
value ((String | Buffer))
Returns
Promise: resolves once the storing is done
Example
// Apply an `Insert` mutation:
let mutationHandle;
window.safeMutableData.newMutation(appHandle)
   .then((h) => mutationHandle = h)
   .then(_ => window.safeMutableDataMutation.insert(mutationHandle, 'key1', 'value1'))
   .then(_ => window.safeMutableData.applyEntriesMutation(mdHandle, mutationHandle))
   .then(_ => console.log('New entry was inserted in the MutableData and committed to the network'));

window.safeMutableDataMutation.remove

src/api/mutable_data_mutation.js

Store a new Remove-action in the transaction

window.safeMutableDataMutation.remove(mutationHandle: MutationHandle, keyName: (String | Buffer), version: Number): Promise
Parameters
mutationHandle (MutationHandle) the Mutation handle
keyName ((String | Buffer)) the key of the entry you want to remove
version (Number) the version successor, to confirm you are actually asking for the right state
Returns
Promise: resolves once the storing is done
Example
// Apply a `Remove` mutation:
let mutationHandle;
window.safeMutableData.newMutation(appHandle)
   .then((h) => mutationHandle = h)
   .then(_ => window.safeMutableData.get(mdHandle, 'key1'))
   .then((value) => window.safeMutableDataMutation.remove(mutationHandle, 'key1', value.version + 1))
   .then(_ => window.safeMutableData.applyEntriesMutation(mdHandle, mutationHandle))
   .then(_ => console.log('Entry was removed from the MutableData and committed to the network'));

window.safeMutableDataMutation.update

src/api/mutable_data_mutation.js

Store a Update-action in the transaction

window.safeMutableDataMutation.update(mutationHandle: MutationHandle, keyName: (String | Buffer), value: (String | Buffer), version: Number): Promise
Parameters
mutationHandle (MutationHandle) the Mutation handle
keyName ((String | Buffer)) the key of the entry you want to update
value ((String | Buffer)) the value to upate to
version (Number) the version successor, to confirm you are actually asking for the right state
Returns
Promise: resolves once the storing is done
Example
// Apply an `Update` mutation:
let mutationHandle;
window.safeMutableData.newMutation(appHandle)
   .then((h) => mutationHandle = h)
   .then(_ => window.safeMutableData.get(mdHandle, 'key1'))
   .then((value) => window.safeMutableDataMutation.update(mutationHandle, 'key1', 'newValue', value.version + 1))
   .then(_ => window.safeMutableData.applyEntriesMutation(mdHandle, mutationHandle))
   .then(_ => console.log('Entry was updated in the MutableData and committed to the network'));

window.safeMutableDataMutation.free

src/api/mutable_data_mutation.js

Free the Mutation instance from memory

window.safeMutableDataMutation.free(mutationHandle: String)
Parameters
mutationHandle (String) the Mutation handle

Mutable Data Permissions

The safeMutableDataPermissions API allows you to manipulate the Permissions of a Mutable Data object in the SAFE network

window.safeMutableDataPermissions.len

src/api/mutable_data_permissions.js

Total number of permissions entries

window.safeMutableDataPermissions.len(permissionsHandle: PermissionsHandle): Promise<Number>
Parameters
permissionsHandle (PermissionsHandle) the Permissions handle
Returns
Promise<Number>: the number of permissions entries
Example
// Retrieving the number of permissions:
window.safeMutableData.getPermissions(mdHandle)
   .then((permsHandle) => window.safeMutableDataPermissions.len(permsHandle))
   .then((len) => console.log('Number of permissions entries in the MutableData: ', len));

window.safeMutableDataPermissions.getPermissionsSet

src/api/mutable_data_permissions.js

Lookup the permissions of a specifc key If the SignKeyHandle provided is null it will be then assumed as for USER_ANYONE.

window.safeMutableDataPermissions.getPermissionsSet(permissionsHandle: PermissionsHandle, signKeyHandle: (SignKeyHandle | null)): Promise<PermissionsSetHandle>
Parameters
permissionsHandle (PermissionsHandle) the Permissions handle
signKeyHandle ((SignKeyHandle | null)) the sign key to lookup for
Returns
Promise<PermissionsSetHandle>: the permissions set for that sign key

window.safeMutableDataPermissions.insertPermissionsSet

src/api/mutable_data_permissions.js

Insert a new permissions to a specifc sign key. Directly commits to the network. Requires 'ManagePermissions'-permission for the app. If the SignKeyHandle provided is null the permission set will be then set for USER_ANYONE.

window.safeMutableDataPermissions.insertPermissionsSet(permissionsHandle: PermissionsHandle, signKeyHandle: (SignKeyHandle | null), pmSetHandle: PermissionsSetHandle): Promise
Parameters
permissionsHandle (PermissionsHandle) the Permissions handle
signKeyHandle ((SignKeyHandle | null)) the sign key to map to
pmSetHandle (PermissionsSetHandle) the permissions set you'd like insert
Returns
Promise: resolves once finished
Example
// Inserting a new permissions set into a MutableData:
let pmSetHandle, appSignKeyHandle, permsHandle;
window.safeCrypto.getAppPubSignKey(appHandle)
   .then((pk) => appSignKeyHandle = pk)
   .then(_ => window.safeMutableData.getPermissions(mdHandle))
   .then((h) => permsHandle = h)
   .then(_ => window.safeMutableData.newPermissionSet(appHandle))
   .then((h) => pmSetHandle = h)
   .then(_ => window.safeMutableDataPermissionsSet.setAllow(pmSetHandle, 'Insert'))
   .then(_ => window.safeMutableDataPermissionsSet.setAllow(pmSetHandle, 'ManagePermissions'))
   .then(_ => window.safeMutableDataPermissions.insertPermissionsSet(permsHandle, appSignKeyHandle, pmSetHandle))
   .then(_ => console.log('Finished inserting new permissions'));

window.safeMutableDataPermissions.forEach

src/api/mutable_data_permissions.js

Iterate over the entries, execute the function every time

window.safeMutableDataPermissions.forEach(permissionsHandle: PermissionsHandle, fn: function (Buffer, ValueVersion)): Promise
Parameters
permissionsHandle (PermissionsHandle) the Permissions handle
fn (function (Buffer, ValueVersion)) the function to call
Returns
Promise: resolves once the iteration is finished
Example
// Iterating over the permissions of a MutableData:
window.safeMutableData.getPermissions(mdHandle)
   .then((permsHandle) => window.safeMutableDataPermissions.forEach(permsHandle, (p) => {
         console.log('Permissions entry handle: ', p);
      }).then(_ => console.log('Iteration finished'))
   );

window.safeMutableDataPermissions.free

src/api/mutable_data_permissions.js

Free the Permissions instance from memory

window.safeMutableDataPermissions.free(permissionsHandle: String)
Parameters
permissionsHandle (String) the Permissions handle

Mutable Data Permissions Set

The safeMutableDataPermissionsSet API allows you to manipulate the Permissions Set of a Mutable Data object in the SAFE network

window.safeMutableDataPermissionsSet.setAllow

src/api/mutable_data_permissions_set.js

Set the action as allowed

window.safeMutableDataPermissionsSet.setAllow(permissionsSetHandle: PermissionsSetHandle, action: MDataAction): Promise
Parameters
permissionsSetHandle (PermissionsSetHandle) the PermissionsSet handle
action (MDataAction) the action to set as allowed
Returns
Promise: resolves when done
Example
// Setting a new permission into a MutableData:
let pmSetHandle, appSignKeyHandle;
window.safeCrypto.getAppPubSignKey(appHandle)
   .then((pk) => appSignKeyHandle = pk)
   .then(_ => window.safeMutableData.newPermissionSet(appHandle))
   .then((h) => pmSetHandle = h)
   .then(_ => window.safeMutableDataPermissionsSet.setAllow(pmSetHandle, 'Delete'))
   .then(_ => window.safeMutableData.getVersion(mdHandle))
   .then((version) => window.safeMutableData.setUserPermissions(mdHandle, appSignKeyHandle, pmSetHandle, version + 1))
   .then(_ => console.log('Finished setting user permission'));

window.safeMutableDataPermissionsSet.setDeny

src/api/mutable_data_permissions_set.js

Set the action as denied

window.safeMutableDataPermissionsSet.setDeny(permissionsSetHandle: PermissionsSetHandle, action: MDataAction): Promise
Parameters
permissionsSetHandle (PermissionsSetHandle) the PermissionsSet handle
action (MDataAction) the action to set as denied
Returns
Promise: resolves when done
Example
// Setting a new permission into a MutableData:
let pmSetHandle, appSignKeyHandle;
window.safeCrypto.getAppPubSignKey(appHandle)
   .then((pk) => appSignKeyHandle = pk)
   .then(_ => window.safeMutableData.newPermissionSet(appHandle))
   .then((h) => pmSetHandle = h)
   .then(_ => window.safeMutableDataPermissionsSet.setDeny(pmSetHandle, 'Update'))
   .then(_ => window.safeMutableData.getVersion(mdHandle))
   .then((version) => window.safeMutableData.setUserPermissions(mdHandle, appSignKeyHandle, pmSetHandle, version + 1))
   .then(_ => console.log('Finished setting user permission'));

window.safeMutableDataPermissionsSet.clear

src/api/mutable_data_permissions_set.js

Remove all permissions for a type of action from the set

window.safeMutableDataPermissionsSet.clear(permissionsSetHandle: PermissionsSetHandle, action: MDataAction): Promise
Parameters
permissionsSetHandle (PermissionsSetHandle) the PermissionsSet handle
action (MDataAction) the action the permissions to be cleared
Returns
Promise: resolves when done
Example
// Setting a new permission into a MutableData:
let pmSetHandle, appSignKeyHandle;
window.safeCrypto.getAppPubSignKey(appHandle)
   .then((pk) => appSignKeyHandle = pk)
   .then(_ => window.safeMutableData.newPermissionSet(appHandle))
   .then((h) => pmSetHandle = h)
   .then(_ => window.safeMutableDataPermissionsSet.clear(pmSetHandle, 'Insert'))
   .then(_ => window.safeMutableData.getVersion(mdHandle))
   .then((version) => window.safeMutableData.setUserPermissions(mdHandle, appSignKeyHandle, pmSetHandle, version + 1))
   .then(_ => console.log('Finished setting user permission'));

window.safeMutableDataPermissionsSet.free

src/api/mutable_data_permissions_set.js

Free the PermissionsSet instance from memory

window.safeMutableDataPermissionsSet.free(permissionsSetHandle: String)
Parameters
permissionsSetHandle (String) the PermissionsSet handle

NFS Emulation

The safeNfs API provides you with a NFS emulation layer rapping a MutableData object

window.safeNfs.create

src/api/emulations/nfs.js

Create a new file with the given content, put the content on the network via ImmutableData (public) and wrap it into a File.

window.safeNfs.create(nfsHandle: NFSHandle, content: (String | Buffer)): Promise<FileHandle>
Parameters
nfsHandle (NFSHandle) the NFS emulation handle
content ((String | Buffer))
Returns
Promise<FileHandle>: the File handle of a newly created file

window.safeNfs.fetch

src/api/emulations/nfs.js

Find the file of the given filename (aka keyName in the MutableData)

window.safeNfs.fetch(nfsHandle: NFSHandle, fileName: String): Promise<FileHandle>
Parameters
nfsHandle (NFSHandle) the NFS emulation handle
fileName (String) the path/file name
Returns
Promise<FileHandle>: the handle of the File found for that path

window.safeNfs.insert

src/api/emulations/nfs.js

Insert the given file into the underlying MutableData, directly commit to the network.

window.safeNfs.insert(nfsHandle: NFSHandle, fileHandle: FileHandle, fileName: (String | Buffer)): Promise<FileHandle>
Parameters
nfsHandle (NFSHandle) the NFS emulation handle
fileHandle (FileHandle) the handle of the File to store
fileName ((String | Buffer)) the path to store the file under
Returns
Promise<FileHandle>: the same File handle

window.safeNfs.update

src/api/emulations/nfs.js

Replace a path with a new file. Directly commit to the network.

window.safeNfs.update(nfsHandle: NFSHandle, fileHandle: FileHandle, fileName: (String | Buffer), version: Number): Promise<FileHandle>
Parameters
nfsHandle (NFSHandle) the NFS emulation handle
fileHandle (FileHandle) the handle of the File to store
fileName ((String | Buffer)) the path to store the file under
version (Number) the version successor, to ensure you are overwriting the right one
Returns
Promise<FileHandle>: the same File handle

window.safeNfs.delete

src/api/emulations/nfs.js

Delete a file from path. Directly commit to the network.

window.safeNfs.delete(nfsHandle: NFSHandle, fileName: (String | Buffer), version: Number): Promise
Parameters
nfsHandle (NFSHandle) the NFS emulation handle
fileName ((String | Buffer)) the path to store the file under
version (Number) the version successor, to ensure you are overwriting the right one
Returns
Promise:

window.safeNfs.open

src/api/emulations/nfs.js

Open a file for reading or writing.

Open Modes:

1 = Replaces the entire content of the file when writing data.

2 = Appends to existing data in the file.

4 = Open file to read.

window.safeNfs.open(nfsHandle: NFSHandle, fileHandle: (FileHandle | null), openMode: Number): Promise<FileHandle>
Parameters
nfsHandle (NFSHandle) the NFS emulation handle
fileHandle ((FileHandle | null)) the handle of the File to open, if null a new file is created
openMode (Number) the mode for opening the file
Returns
Promise<FileHandle>: a new File handle

window.safeNfs.free

src/api/emulations/nfs.js

Free the NFS emulation instance from memory

window.safeNfs.free(nfsHandle: NFSHandle)
Parameters
nfsHandle (NFSHandle) the NFS emulation handle

window.safeNfsFile.size

src/api/emulations/nfs_file.js

Get current file size

window.safeNfsFile.size(fileHandle: FileHandle): Promise<Number>
Parameters
fileHandle (FileHandle) the File handle
Returns
Promise<Number>: the file size

window.safeNfsFile.read

src/api/emulations/nfs_file.js

Read content from the file

window.safeNfsFile.read(fileHandle: FileHandle, position: Number, len: Number): Promise<[Data, Size]>
Parameters
fileHandle (FileHandle) the File handle
position (Number)
len (Number)
Returns
Promise<[Data, Size]>:

window.safeNfsFile.write

src/api/emulations/nfs_file.js

Write content into the file

window.safeNfsFile.write(fileHandle: FileHandle, content: (Buffer | String)): Promise
Parameters
fileHandle (FileHandle) the File handle
content ((Buffer | String))
Returns
Promise:

window.safeNfsFile.close

src/api/emulations/nfs_file.js

Close the file, this will commit the content to the network.

window.safeNfsFile.close(fileHandle: FileHandle): Promise
Parameters
fileHandle (FileHandle) the File handle
Returns
Promise:

window.safeNfsFile.metadata

src/api/emulations/nfs_file.js

Retrieve the file's metadata.

window.safeNfsFile.metadata(fileHandle: FileHandle): FileMetadata
Parameters
fileHandle (FileHandle) the File handle
Returns
FileMetadata: the file's metadata

window.safeNfsFile.free

src/api/emulations/nfs_file.js

Free the NFS File instance from memory

window.safeNfsFile.free(fileHandle: FileHandle)
Parameters
fileHandle (FileHandle) the File handle

Cipher Opt

The safeCipherOpt API provides you with functions to create different cipher options

window.safeCipherOpt.newPlainText

src/api/cipher_opt.js

Create a PlainText Cipher Opt

window.safeCipherOpt.newPlainText(appHandle: SAFEAppHandle): CipherOptHandle
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
CipherOptHandle: the CipherOpt handle
Example
// Creating a plain test cipher opt object:
window.safeCipherOpt.newPlainText(appHandle)

window.safeCipherOpt.newSymmetric

src/api/cipher_opt.js

Create a new Symmetric Cipher

window.safeCipherOpt.newSymmetric(appHandle: SAFEAppHandle): CipherOptHandle
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
CipherOptHandle: the CipherOpt handle
Example
// Creating a symmetric cipher opt object:
window.safeCipherOpt.newSymmetric(appHandle)

window.safeCipherOpt.newAsymmetric

src/api/cipher_opt.js

Create a new Asymmetric Cipher for the given key

window.safeCipherOpt.newAsymmetric(keyHandle: EncKeyHandle): CipherOptHandle
Parameters
keyHandle (EncKeyHandle) the EncKey handle
Returns
CipherOptHandle: the CipherOpt handle
Example
// Creating an assymetric cipher opt object:
window.safeCipherOpt.newAsymmetric(appHandle)

window.safeCipherOpt.free

src/api/cipher_opt.js

Free the CipherOpt instance from memory

window.safeCipherOpt.free(cipherOptHandle: CipherOptHandle)
Parameters
cipherOptHandle (CipherOptHandle) the CipherOpt handle

Crypto

The safeCrypto API functions provide you with handy cryptographic functions

window.safeCrypto.sha3Hash

src/api/crypto.js

Hash the given input with SHA3 Hash

window.safeCrypto.sha3Hash(appHandle: SAFEAppHandle, data: (String | Buffer)): Promise<Buffer>
Parameters
appHandle (SAFEAppHandle) the app handle
data ((String | Buffer)) the input string
Returns
Promise<Buffer>: the hash generated
Example
// Generating a hash:
window.safeCrypto.sha3Hash(appHandle, '1010101010101')
   .then((hash) => console.log('SHA3 Hash generated: ', hash.toString('hex')));

window.safeCrypto.getAppPubSignKey

src/api/crypto.js

Get the application's public signing key

window.safeCrypto.getAppPubSignKey(appHandle: SAFEAppHandle): Promise<SignKeyHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
Promise<SignKeyHandle>: the SignKey handle
Example
// Retrieving application's public sign key:
window.safeCrypto.getAppPubSignKey(appHandle)
   .then((signKeyHandle) => window.safeCryptoSignKey.getRaw(signKeyHandle))
   .then((rawPk) => console.log('App\'s public sign key: ', rawPk.buffer.toString('hex')));

window.safeCrypto.getAppPubEncKey

src/api/crypto.js

Get the application's public encryption key

window.safeCrypto.getAppPubEncKey(appHandle: SAFEAppHandle): Promise<PubEncKeyHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
Promise<PubEncKeyHandle>: the PubEncKey handle
Example
// Retrieving application's public encryption key:
window.safeCrypto.getAppPubEncKey(appHandle)
   .then((pubEncKeyHandle) => window.safeCryptoPubEncKey.getRaw(pubEncKeyHandle))
   .then((rawPk) => console.log('App\'s public encryption key: ', rawPk.buffer.toString('hex')));

window.safeCrypto.generateEncKeyPair

src/api/crypto.js

Generate a new Asymmetric EncryptionKeyPair

window.safeCrypto.generateEncKeyPair(appHandle: SAFEAppHandle): Promise<KeyPairHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
Promise<KeyPairHandle>: the KeyPair handle
Example
// Generating encryption key pair:
window.safeCrypto.generateEncKeyPair(appHandle)
   .then((encKeyPairHandle) => window.safeCryptoKeyPair.getPubEncKey(encKeyPairHandle))
   .then((pubEncKeyHandle) => window.safeCryptoPubEncKey.getRaw(pubEncKeyHandle))
   .then((rawPk) => console.log('Public encryption key generated: ', rawPk.buffer.toString('hex')));

window.safeCrypto.getSignKeyFromRaw

src/api/crypto.js

Interpret the SignKey from a given raw string

window.safeCrypto.getSignKeyFromRaw(appHandle: SAFEAppHandle, raw: (String | Buffer)): Promise<SignKeyHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
raw ((String | Buffer)) the raw input string
Returns
Promise<SignKeyHandle>: the SignKey handle
Example
// Interpreting a sign key from a raw string:
window.safeCrypto.getAppPubSignKey(appHandle)
   .then((signKeyHandle) => window.safeCryptoSignKey.getRaw(signKeyHandle))
   .then((raw) => window.safeCrypto.getSignKeyFromRaw(appHandle, raw))
   .then((signKeyHandle) => window.safeCryptoSignKey.getRaw(signKeyHandle))
   .then((rawSignKey) => console.log('Sign key: ', rawSignKey.buffer.toString('hex')));

window.safeCrypto.pubEncKeyKeyFromRaw

src/api/crypto.js

Interprete a public encryption Key from a given raw string

window.safeCrypto.pubEncKeyKeyFromRaw(appHandle: SAFEAppHandle, raw: (String | Buffer)): Promise<PubEncKeyHandle>
Parameters
appHandle (SAFEAppHandle) the app handle
raw ((String | Buffer)) the raw input string
Returns
Promise<PubEncKeyHandle>: the PubEncKey handle
Example
// Interpreting a public encryption key from a raw string:
window.safeCrypto.getAppPubEncKey(appHandle)
   .then((pubEncKeyHandle) => window.safeCryptoPubEncKey.getRaw(pubEncKeyHandle))
   .then((raw) => window.safeCrypto.pubEncKeyKeyFromRaw(appHandle, raw))
   .then((pubEncKeyHandle) => window.safeCryptoPubEncKey.getRaw(pubEncKeyHandle))
   .then((rawPubEncKey) => console.log('Public encrpytion key: ', rawPubEncKey.buffer.toString('hex')));

window.safeCrypto.secEncKeyKeyFromRaw

src/api/crypto.js

Interpret a secret encryption Key from a given raw string

window.safeCrypto.secEncKeyKeyFromRaw(appHandle: SAFEAppHandle, raw: (String | Buffer)): Promise<SecEncKey>
Parameters
appHandle (SAFEAppHandle) the app handle
raw ((String | Buffer)) the raw input string
Returns
Promise<SecEncKey>: the SecEncKey handle
Example
// Interpreting a secret encryption key from a raw string:
window.safeCrypto.generateEncKeyPair(appHandle)
   .then((encKeyPairHandle) => window.safeCryptoKeyPair.getSecEncKey(encKeyPairHandle))
   .then((secEncKeyHandle) => window.safeCryptoSecEncKey.getRaw(secEncKeyHandle))
   .then((raw) => window.safeCrypto.secEncKeyKeyFromRaw(appHandle, raw))
   .then((secEncKeyHandle) => window.safeCryptoSecEncKey.getRaw(secEncKeyHandle))
   .then((rawSecEncKey) => console.log('Secret encrpytion key: ', rawSecEncKey.buffer.toString('hex')));

window.safeCrypto.generateEncKeyPairFromRaw

src/api/crypto.js

Generate a new Asymmetric EncryptionKeyPair from raw secret and public keys

window.safeCrypto.generateEncKeyPairFromRaw(appHandle: SAFEAppHandle, rawPublicKey: (String | Buffer), rawSecretKey: (String | Buffer)): Promise<KeyPair>
Parameters
appHandle (SAFEAppHandle) the app handle
rawPublicKey ((String | Buffer)) the raw public key string
rawSecretKey ((String | Buffer)) the raw secret key string
Returns
Promise<KeyPair>: the KeyPair handle
Example
// Generting an encryption key pair from raw secret and public encryption key strings:
window.safeCrypto.generateEncKeyPair(appHandle)
   .then((encKeyPairHandle) => window.safeCryptoKeyPair.getSecEncKey(encKeyPairHandle)
      .then((secEncKeyHandle) => window.safeCryptoSecEncKey.getRaw(secEncKeyHandle)
         .then((rawSecEncKey) => window.safeCryptoKeyPair.getPubEncKey(encKeyPairHandle)
            .then((pubEncKeyHandle) => window.safeCryptoPubEncKey.getRaw(pubEncKeyHandle))
            .then((rawPubEncKey) => window.safeCrypto.generateEncKeyPairFromRaw(appHandle, rawPubEncKey, rawSecEncKey))
            .then((encKeyPairHandle) => console.log('Encryption key pair generated from raw strings'))
         )));

window.safeCryptoKeyPair.getPubEncKey

src/api/crypto_key_pair.js

Get the Public Encryption Key instance of this key pair

window.safeCryptoKeyPair.getPubEncKey(keyPairHandle: KeyPairHandle): Promise<PubEncKeyHandle>
Parameters
keyPairHandle (KeyPairHandle) the KeyPair handle
Returns
Promise<PubEncKeyHandle>: the PubEncKey handle
Example
// Getting the public encryption key from a key pair:
window.safeCrypto.generateEncKeyPair(appHandle)
   .then((encKeyPairHandle) => window.safeCryptoKeyPair.getPubEncKey(encKeyPairHandle))
   .then((pubEncKeyHandle) => window.safeCryptoPubEncKey.getRaw(pubEncKeyHandle))
   .then((rawPk) => console.log('Public encryption key: ', rawPk.buffer.toString('hex')));

window.safeCryptoKeyPair.getSecEncKey

src/api/crypto_key_pair.js

Get the Secrect Encryption Key instance of this key pair

window.safeCryptoKeyPair.getSecEncKey(keyPairHandle: KeyPairHandle): Promise<SecEncKeyHandle>
Parameters
keyPairHandle (KeyPairHandle) the KeyPair handle
Returns
Promise<SecEncKeyHandle>: the SecEncKey handle
Example
// Getting the secret encryption key from a key pair:
window.safeCrypto.generateEncKeyPair(appHandle)
   .then((encKeyPairHandle) => window.safeCryptoKeyPair.getSecEncKey(encKeyPairHandle))
   .then((secEncKeyHandle) => window.safeCryptoSecEncKey.getRaw(secEncKeyHandle))
   .then((rawSk) => console.log('Secret encryption key: ', rawSk.buffer.toString('hex')));

window.safeCryptoKeyPair.decryptSealed

src/api/crypto_key_pair.js

Decrypt the given ciphertext with a seal (buffer or string) using the private and public key

window.safeCryptoKeyPair.decryptSealed(keyPairHandle: KeyPairHandle, cipher: (String | Buffer)): Promise<Buffer>
Parameters
keyPairHandle (KeyPairHandle) the KeyPair handle
cipher ((String | Buffer)) the chiper text to decrypt
Returns
Promise<Buffer>: the decrypted data

window.safeCryptoKeyPair.free

src/api/crypto_key_pair.js

Free the KeyPair instance from memory

window.safeCryptoKeyPair.free(keyPairHandle: KeyPairHandle)
Parameters
keyPairHandle (KeyPairHandle) the KeyPair handle

window.safeCryptoPubEncKey.getRaw

src/api/crypto_public_encryption_key.js

Generate raw string copy of public encryption key

window.safeCryptoPubEncKey.getRaw(pubEncKeyHandle: PubEncKeyHandle): Promise<String>
Parameters
pubEncKeyHandle (PubEncKeyHandle) the PubEncKey handle
Returns
Promise<String>: the raw encryption key string
Example
// Generating a raw string copy of the public encryption key:
window.safeCrypto.generateEncKeyPair(appHandle)
   .then((encKeyPairHandle) => window.safeCryptoKeyPair.getPubEncKey(encKeyPairHandle))
   .then((pubEncKeyHandle) => window.safeCryptoPubEncKey.getRaw(pubEncKeyHandle))
   .then((rawPk) => console.log('Public encryption key: ', rawPk.buffer.toString('hex')));

window.safeCryptoPubEncKey.encryptSealed

src/api/crypto_public_encryption_key.js

Encrypt the input (buffer or string) using the private and public key with a seal

window.safeCryptoPubEncKey.encryptSealed(pubEncKeyHandle: PubEncKeyHandle, str: (String | Buffer)): Promise<Buffer>
Parameters
pubEncKeyHandle (PubEncKeyHandle) the PubEncKey handle
str ((String | Buffer)) the input string to encrypt
Returns
Promise<Buffer>: the encrpted data

window.safeCryptoPubEncKey.encrypt

src/api/crypto_public_encryption_key.js

Encrypt the input (buffer or string) using the private and public key and the given private key

window.safeCryptoPubEncKey.encrypt(pubEncKeyHandle: PubEncKeyHandle, str: (String | Buffer), secretKey: String): Promise<Buffer>
Parameters
pubEncKeyHandle (PubEncKeyHandle) the PubEncKey handle
str ((String | Buffer)) the input string to encrypt
secretKey (String) a secrect encryption key string
Returns
Promise<Buffer>:

window.safeCryptoPubEncKey.free

src/api/crypto_public_encryption_key.js

Free the PubEncKey instance from memory

window.safeCryptoPubEncKey.free(pubEncKeyHandle: PubEncKeyHandle)
Parameters
pubEncKeyHandle (PubEncKeyHandle) the PubEncKey handle

window.safeCryptoSecEncKey.getRaw

src/api/crypto_secret_encryption_key.js

Generate raw string copy of the secret encryption key

window.safeCryptoSecEncKey.getRaw(secEncKeyHandle: SecEncKeyHandle): Promise<String>
Parameters
secEncKeyHandle (SecEncKeyHandle) the SecEncKey handle
Returns
Promise<String>: the raw secret encryption key string
Example
// Generating a raw string copy of the secret encryption key:
window.safeCrypto.generateEncKeyPair(appHandle)
   .then((encKeyPairHandle) => window.safeCryptoKeyPair.getSecEncKey(encKeyPairHandle))
   .then((secEncKeyHandle) => window.safeCryptoSecEncKey.getRaw(secEncKeyHandle))
   .then((rawSk) => console.log('Secret encryption key: ', rawSk.buffer.toString('hex')));

window.safeCryptoSecEncKey.decrypt

src/api/crypto_secret_encryption_key.js

Decrypt the given ciphertext (buffer or string) using the private and public key

window.safeCryptoSecEncKey.decrypt(secEncKeyHandle: SecEncKeyHandle, cipher: (String | Buffer), theirPubKey: String): Promise<Buffer>
Parameters
secEncKeyHandle (SecEncKeyHandle) secret encryption key handle
cipher ((String | Buffer)) the cipher text
theirPubKey (String) a public key
Returns
Promise<Buffer>: the decrypted data

window.safeCryptoSecEncKey.free

src/api/crypto_secret_encryption_key.js

Free the SecEncKey instance from memory

window.safeCryptoSecEncKey.free(secEncKeyHandle: SecEncKeyHandle)
Parameters
secEncKeyHandle (SecEncKeyHandle) the SecEncKey handle

window.safeCryptoSignKey.getRaw

src/api/crypto_sign_key.js

Generate raw string copy of the public signature key

window.safeCryptoSignKey.getRaw(signKeyHandle: SignKeyHandle): Promise<String>
Parameters
signKeyHandle (SignKeyHandle) the public SignKey handle
Returns
Promise<String>: the raw signature key string
Example
// Retrieving a raw string copy of the sign key:
window.safeCrypto.getAppPubSignKey(appHandle)
   .then((signKeyHandle) => window.safeCryptoSignKey.getRaw(signKeyHandle))
   .then((rawPk) => console.log('Sign key: ', rawPk.buffer.toString('hex')));

window.safeCryptoSignKey.free

src/api/crypto_sign_key.js

Free the SignKey instance from memory

window.safeCryptoSignKey.free(signKeyHandle: SignKeyHandle)
Parameters
signKeyHandle (SignKeyHandle) the SignKey handle

Types

SAFEAppHandle

src/api/app.js

Holds the reference to a SAFEApp instance which is the primary interface to interact with the SAFE network. Note that it is required to free the memory used by such an instance when it's not needed anymore by the client aplication, please refer to the free function.

SAFEAppHandle

Type: String

The auth URI ('safe-auth://...') returned by the Authenticator after the user has authorised the application. This URL can be used by the application to connect to the network wihout the need to get authorisation from the Authenticator again. Although if the user decided to revoke the application the auth URI shall be obtained again from the Authenticator.

AuthURI

Type: String

Holds the information about tha client application, needed for authentication.

AppInfo

Type: Object

Parameters
id (String) unique identifier for the app (e.g. 'net.maidsafe.examples.mail-app')
name (String) human readable name of the app (e.g. "Mail App")
vendor (String) human readable name of the vendor (e.g. "MaidSafe Ltd.")

MutableDataHandle

src/api/mutable_data.js

Holds the reference to a MutableData instance. Note that it is required to free the memory used by such an instance when it's not needed anymore by the client aplication, please refer to the free function.

MutableDataHandle

Type: String

Holds the reference to a ImmutableData Writer instance. Note that such an instance it's free from memory when the close function is invoked.

WriterHandle

Type: String

Holds the reference to a ImmutableData Reader instance. Note that it is required to free the memory used by such an instance when it's not needed anymore by the client aplication, please refer to the free function.

ReaderHandle

Type: String

Holds the reference to an Entries instance. Note that it is required to free the memory used by such an instance when it's not needed anymore by the client aplication, please refer to the free function.

EntriesHandle

Type: String

Holds the reference to a Keys instance. Note that it is required to free the memory used by such an instance when it's not needed anymore by the client aplication, please refer to the free function.

KeysHandle

Type: String

Holds the reference to a Values instance. Note that it is required to free the memory used by such an instance when it's not needed anymore by the client aplication, please refer to the free function.

ValuesHandle

Type: String

Holds the reference to a Mutation instance. Note that it is required to free the memory used by such an instance when it's not needed anymore by the client aplication, please refer to the free function.

MutationHandle

Type: String

Holds the reference to a Permissions instance. Note that it is required to free the memory used by such an instance when it's not needed anymore by the client aplication, please refer to the free function.

PermissionsHandle

Type: String

Holds the reference to a PermissionsSet instance. Note that it is required to free the memory used by such an instance when it's not needed anymore by the client aplication, please refer to the free function.

PermissionsSetHandle

Type: String

Holds the reference to a NFS emulation instance. Note that it is required to free the memory used by such an instance when it's not needed anymore by the client aplication, please refer to the free function.

NFSHandle

Type: String

Holds the reference to a File instance. Note that it is required to free the memory used by such an instance when it's not needed anymore by the client aplication, please refer to the free function.

FileHandle

Type: String

FileMetadata

Type: Object

Parameters
fileHandle (any)
dataMapName (Buffer) The XorName where to read the immutable data at
created (Date) When was this created? in UTC
modified (Date) When was this last modified? in UTC
version (Number) Which version was this? Equals the underlying MutableData's entry version

CipherOptHandle

src/api/cipher_opt.js

Holds the reference to a CipherOpt instance. Note that it is required to free the memory used by such an instance when it's not needed anymore by the client aplication, please refer to the free function.

CipherOptHandle

Type: String

Holds the reference to a KeyPair instance. Note that it is required to free the memory used by such an instance when it's not needed anymore by the client aplication, please refer to the free function.

KeyPairHandle

Type: String

Holds the reference to a PubEncKey instance. Note that it is required to free the memory used by such an instance when it's not needed anymore by the client aplication, please refer to the free function.

PubEncKeyHandle

Type: String

Holds the reference to a SecEncKey instance. Note that it is required to free the memory used by such an instance when it's not needed anymore by the client aplication, please refer to the free function.

SecEncKeyHandle

Type: String

Holds the reference to a public SignKey instance. Note that it is required to free the memory used by such an instance when it's not needed anymore by the client aplication, please refer to the free function.

SignKeyHandle

Type: String

window.safeApp.reconnect

src/api/app.js

Reconnect SAFEApp instance if connection is disconnected

window.safeApp.reconnect(appHandle: SAFEAppHandle)
Parameters
appHandle (SAFEAppHandle) the app handle

window.safeApp.logPath

src/api/app.js

Generate the log path for the provided filename. If the filename provided is null, it then returns the path of where the safe_core log file is located.

window.safeApp.logPath(appHandle: SAFEAppHandle, filename: String): Promise<String>
Parameters
appHandle (SAFEAppHandle) the app handle
filename (String = null) log filename to generate the path
Returns
Promise<String>: the log filename path generated
Example
// Retrieve the '_public' container:
window.safeApp.logPath(appHandle, 'mylogfile.log')
   .then((path) => console.log('Log path generated: ', path));

window.safeCrypto.generateNonce

src/api/crypto.js

Generate a nonce that can be used when creating private MutableData

window.safeCrypto.generateNonce(appHandle: SAFEAppHandle): Promise<Buffer>
Parameters
appHandle (SAFEAppHandle) the app handle
Returns
Promise<Buffer>: the nonce generated
Example
// Generating a nonce:
window.safeCrypto.generateNonce(appHandle)
   .then((nonce) => console.log('Nonce generated: ', nonce.buffer.toString('hex')));