### @maidsafe/safe-node-app

`0.3.0`
Need help reading this?

## External API

The externally exposed API

### initializeApp

src/index.js

The main entry point to create a new SAFEApp

initializeApp(appInfo: AppInfo, networkStateCallBack: Function, options: InitOptions?): Promise<SAFEApp>
Parameters
appInfo `(AppInfo)`
networkStateCallBack `(Function = `null`)` callback function to receive network state updates
options `(InitOptions?)` initialisation options
Returns
`Promise<SAFEApp>`: promise to a SAFEApp instance
Example

    // Usage Example
    const safe = require('safe');

    // starting initialisation
    let prms = safe.initializeApp({
                         id: "net.maidsafe.example",
                         name: 'Example App',
                         vendor: 'MaidSafe Ltd.'
                        });
    // we want read-append access to `_pictures` and
    // read access to `_videos`:
    const containers = { '_videos': ['Read'], '_pictures' : ['Read', 'Insert']}
    prms.then(app => app.auth.genAuthUri(containers
              ).then(uri => app.auth.openUri(uri)
           // now we either quit the programm
           // or wait for a result url
           ))

### fromAuthURI

src/index.js

If you have received a response URI (which you are allowed to store securely), you can directly get an authenticated or non-authenticated connection by using this helper function. Just provide said URI as the second value.

fromAuthURI(appInfo: AppInfo, authUri: String, networkStateCallBack: Function, options: InitOptions?): Promise<SAFEApp>
Parameters
appInfo `(AppInfo)` the app info
authUri `(String)` the URI coming back from the Authenticator
networkStateCallBack `(Function = `null`)` optional callback function to receive network state updates
options `(InitOptions?)` initialisation options
Returns
`Promise<SAFEApp>`: promise to a SAFEApp instance

### AppInfo

src/index.js
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.")
scope `(String?)` an optional scope of this instance
customExecPath `(String?)` an optional customised execution path to use when registering the URI with the system.

### InitOptions

src/index.js
InitOptions

Type: Object

Parameters
registerScheme `(Boolean?)` to register auth scheme with the OS. Defaults to true
joinSchemes `(Array?)` to additionally register custom protocol schemes
log `(Boolean?)` to enable or disable back end logging. Defaults to true
libPath `(String?)` path to the folder where the native libs can be found. Defaults to current folder path.

## App Interface

the App and the API it exposes

### SAFEApp

src/app.js

Holds one sessions with the network and is the primary interface to interact with the network. As such it also provides all API-Providers connected through this session.

new SAFEApp(appInfo: any, networkStateCallBack: any, options: any)

Extends EventEmitter

Parameters
appInfo `(any)`
networkStateCallBack `(any)`
options `(any)`
Static Members
▸ fromAuthUri(appInfo, authUri, networkStateCallBack, options, initialisation)
src/app.js

Create a SAFEApp and try to login it through the `authUri`

fromAuthUri(appInfo: AppInfo, authUri: String, networkStateCallBack: Function, options: any, initialisation: InitOptions): Promise<SAFEApp>
Parameters
appInfo `(AppInfo)` the AppInfo
authUri `(String)` URI containing the authentication info
networkStateCallBack `(Function = `null`)` optional callback function to receive network state updates
options `(any)`
initialisation `(InitOptions)` options
Returns
`Promise<SAFEApp>`: authenticated and connected SAFEApp
Instance Members
▸ auth
src/app.js

get the AuthInterface instance connected to this session

auth
Returns
`AuthInterface`:
▸ crypto
src/app.js

get the Crypto instance connected to this session

crypto
Returns
`CryptoInterface`:
▸ cipherOpt
src/app.js

get the CipherOptInterface instance connected to this session

cipherOpt
Returns
`CipherOptInterface`:
▸ immutableData
src/app.js

get the ImmutableDataInterface instance connected to this session

immutableData
Returns
`ImmutableDataInterface`:
▸ mutableData
src/app.js

get the MutableDataInterface instance connected to this session

mutableData
Returns
`MutableDataInterface`:
▸ webFetch(url)
src/app.js

Helper to lookup a given `safe://`-url in accordance with the convention and find the requested object.

webFetch(url: String): Promise<File>
Parameters
url `(String)` the url you want to fetch
Returns
`Promise<File>`: the file object found for that URL
▸ connection
src/app.js

The current connection object hold on the Rust-Side

connection
Returns
`Pointer`:
▸ networkState
src/app.js

The current Network state

networkState
Returns
`String`: of latest state
▸ appInfo
src/app.js

The current appInfo

appInfo
▸ logPath(logFilename)
src/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.

logPath(logFilename: String): Promise<String>
Parameters
logFilename `(String = `null`)` optional log filename to generate the path
Returns
`Promise<String>`:
▸ reconnect()
src/app.js

Reconnect to the metwork Must be invoked when the client decides to connect back after the connection is disconnected.

reconnect()

### CryptoInterface

src/api/crypto.js

Encryption functionality for the app

Access it through your {SAFEApp} instance under `app.crypto`

new CryptoInterface(app: any)
Parameters
app `(any)`
Instance Members
▸ sha3Hash(inpt)
src/api/crypto.js

Hash the given input with SHA3 Hash

sha3Hash(inpt: any): Promise<Buffer>
Parameters
inpt `(any)`
Returns
`Promise<Buffer>`:
▸ getAppPubSignKey()
src/api/crypto.js

Get the public signing key of this session

getAppPubSignKey(): Promise<SignKey>
Returns
`Promise<SignKey>`:
▸ getAppPubEncKey()
src/api/crypto.js

Get the public encryption key of this session

getAppPubEncKey(): Promise<PubEncKey>
Returns
`Promise<PubEncKey>`:
▸ generateEncKeyPair()
src/api/crypto.js

Generate a new Asymmetric EncryptionKeyPair

generateEncKeyPair(): Promise<KeyPair>
Returns
`Promise<KeyPair>`:
▸ generateEncKeyPairFromRaw(rawPublicKey, rawSecretkey)
src/api/crypto.js

Generate a new Asymmetric EncryptionKeyPair from raw secret and public keys

generateEncKeyPairFromRaw(rawPublicKey: any, rawSecretkey: any): Promise<KeyPair>
Parameters
rawPublicKey `(any)`
rawSecretkey `(any)`
Returns
`Promise<KeyPair>`:
▸ getSignKeyFromRaw(raw)
src/api/crypto.js

Interprete the SignKey from a given raw string

getSignKeyFromRaw(raw: String): Promise<SignKey>
Parameters
raw `(String)` sign key raw bytes as string
Returns
`Promise<SignKey>`:
▸ pubEncKeyKeyFromRaw(raw)
src/api/crypto.js

Interprete the public encryption Key from a given raw string

pubEncKeyKeyFromRaw(raw: String): Promise<PubEncKey>
Parameters
raw `(String)` public encryption key raw bytes as string
Returns
`Promise<PubEncKey>`:
▸ secEncKeyKeyFromRaw(raw)
src/api/crypto.js

Interprete the secret encryption Key from a given raw string

secEncKeyKeyFromRaw(raw: String): Promise<SecEncKey>
Parameters
raw `(String)` secret encryption key raw bytes as string
Returns
`Promise<SecEncKey>`:
▸ generateNonce()
src/api/crypto.js

Generate a nonce that can be used when creating private MutableData

generateNonce(): Promise<Nonce>
Returns
`Promise<Nonce>`: the nonce generated

### AuthInterface

src/api/auth.js

The AuthInterface contains all authentication related functionality with the network. Like creating an authenticated or unauthenticated connection or create messages for the IPC authentitcation protocol.

Access your instance through ypur {SAFEApp} instance under `.auth`.

new AuthInterface(app: any)
Parameters
app `(any)`
Instance Members
▸ registered
src/api/auth.js

Whether or not this is a registered/authenticated session.

registered
Returns
`Boolean`: true if this is an authenticated session
▸ genAuthUri(permissions, opts?)
src/api/auth.js

Generate an authentication URI for the app with the given permissions and optional parameters.

genAuthUri(permissions: Object, opts: Object?): String
Parameters
permissions `(Object)` mapping the container-names to a list of permissions you want to request
opts `(Object?)` optional parameters

Name | Description
--- | ---
opts.own_container `Boolean` (default `false`) | whether or not to request our own container to be created for us, too

Returns
`String`: `safe-auth://` -URI
Example

    // using an Authentication example:
    app.auth.genAuthUri({
     _public: ['Insert'], // request to insert into public
     _other: ['Insert', 'Update'] // request to insert and update
    }, {own_container: true}) // and we want our own container, too

▸ genShareMDataUri(permissions)
src/api/auth.js

Generate a `'safe-auth'`-URI to request permissions on arbitrary owned MutableData's.

genShareMDataUri(permissions: Object): String
Parameters
permissions `(Object)` mapping the MutableData's XoR names to a list of permissions you want to request
Returns
`String`: `safe-auth://` -URI
Example

    // example of requesting permissions for a couple of MutableData's:
    app.auth.genShareMDataUri([
     { type_tag: 15001,   // request for MD with tag 15001
       name: 'XoRname1',  // request for MD located at address 'XoRname1'
       perms: ['Insert'], // request for inserting into the referenced MD
     },
     { type_tag: 15020,   // request for MD with tag 15020
       name: 'XoRname2',  // request for MD located at address 'XoRname2'
       perms: ['Insert', `Update`], // request for updating and inserting into the referenced MD
     }
    ])

▸ genConnUri()
src/api/auth.js

Generate an unregistered connection URI for the app.

genConnUri(): String
Returns
`String`: `safe-auth://` -URI
Example

    // using an Authentication example:
    app.auth.genConnUri()

▸ openUri(uri)
src/api/auth.js

Open the given Authentication URI to the authenticator

openUri(uri: any)
Parameters
uri `(any)`
▸ genContainerAuthUri(containers)
src/api/auth.js

Generate a `'safe-auth'`-URI to request further container permissions

genContainerAuthUri(containers: Object): String
Parameters
containers `(Object)` mapping container name to list of permissions
Returns
`String`:
Example

    // generating a container authorisation URI:
    app.auth.genContainerAuthUri(
     _publicNames: ['Insert'], // request to insert into publicNames
    })

▸ refreshContainersPermissions()
src/api/auth.js

Refresh the access persmissions from the network. Useful when you just connected or received a response from the authenticator in the IPC protocol.

refreshContainersPermissions(): Promise
Returns
`Promise`:
▸ getContainersPermissions()
src/api/auth.js

Get the names of all containers found and the app's granted permissions for each of them.

getContainersPermissions(): Promise<[ContainersPerms]>
Returns
`Promise<[ContainersPerms]>`:
▸ getOwnContainer()
src/api/auth.js

Get the MutableData for the app's own container generated by Authenticator. When run in tests, this falls back to the randomly generated version

getOwnContainer(): Promise<MutableData>
Returns
`Promise<MutableData>`:
▸ canAccessContainer(name, permissions)
src/api/auth.js

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

canAccessContainer(name: String, permissions: any): Promise<bool>
Parameters
name `(String)` name of the container, e.g. `'_public'`
permissions `(any)`
Returns
`Promise<bool>`:
▸ getContainer(name)
src/api/auth.js

Lookup and return the information necessary to access a container.

getContainer(name: any): Promise<MutableData>
Parameters
name `(any)` {String} name of the container, e.g. `'_public'`
Returns
`Promise<MutableData>`: the MutableData behind it
▸ loginFromURI(responseUri)
src/api/auth.js

Create a new authenticated or unregistered session using the provided IPC response.

loginFromURI(responseUri: String): Promise<SAFEApp>
Parameters
responseUri `(String)` the IPC response string given
Returns
`Promise<SAFEApp>`: the given app instance with a newly setup and authenticated session.
▸ loginForTest(access)
src/api/auth.js

ONLY AVAILALBE IF RUN in NODE_ENV='development' || 'testing'

Generate a locally registered App with the given permissions, or a local unregistered App if permissions is `null`.

loginForTest(access: any): Promise<SAFEApp>
Parameters
access `(any)`
Returns
`Promise<SAFEApp>`: the locally registered/unregistered App instance

### CipherOptInterface

src/api/cipher_opt.js

Provide the Cipher Opt API

new CipherOptInterface(app: any)
Parameters
app `(any)`
Instance Members
▸ newPlainText()
src/api/cipher_opt.js

Create a PlainText Cipher Opt

newPlainText(): CipherOpt
Returns
`CipherOpt`:
▸ newSymmetric()
src/api/cipher_opt.js

Create a new Symmetric Cipher

newSymmetric(): CipherOpt
Returns
`CipherOpt`:
▸ newAsymmetric(key)
src/api/cipher_opt.js

Create a new Asymmetric Cipher for the given key

newAsymmetric(key: EncKey): CipherOpt
Parameters
key `(EncKey)`
Returns
`CipherOpt`:

### ImmutableDataInterface

src/api/immutable.js

Interact with Immutable Data of the Network through this Interface.

Access it through your {SAFEApp} instance under `app.immutableData`

new ImmutableDataInterface(app: any)
Parameters
app `(any)`
Instance Members
▸ create()
src/api/immutable.js

Create a new ImmutableDataInterface

create(): Promise<Writer>
Returns
`Promise<Writer>`:
▸ fetch(address)
src/api/immutable.js

Look up an existing Immutable Data for the given address

fetch(address: Buffer): Promise<Reader>
Parameters
address `(Buffer)` the XorName on the network
Returns
`Promise<Reader>`:

### MutableDataInterface

src/api/mutable.js

Provide the MutableData API for the session.

Access via `mutableData` on your app Instance.

new MutableDataInterface(app: any)
Parameters
app `(any)`
Example

    // using mutable Data
    app.mutableData.newRandomPublic(15001)
      // set it up with starting data
      .then((mdata) => mdata.quickSetup({keyA: 'input value'})
       .then(() => mdata.getNameAndTag())) // return name and tag

    // now read using name and tag
    .then((ref) => app.mutableData.newPublic(ref.name, ref.tag)
      .then((mdata) => mdata.get('keyA').then((val) => {
        should(val.buf.toString()).equal('input value');
      })))

Instance Members
▸ newRandomPrivate(typeTag)
src/api/mutable.js

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

newRandomPrivate(typeTag: Number): Promise<MutableData>
Parameters
typeTag `(Number)` the typeTag to use
Returns
`Promise<MutableData>`:
▸ newRandomPublic(typeTag)
src/api/mutable.js

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

newRandomPublic(typeTag: Number): Promise<MutableData>
Parameters
typeTag `(Number)` the typeTag to use
Returns
`Promise<MutableData>`:
▸ newPrivate(name, typeTag, secKey, nonce)
src/api/mutable.js

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

newPrivate(name: (Buffer | String), typeTag: Number, secKey: (Buffer | String), nonce: (Buffer | String)): Promise<MutableData>
Parameters
name `((Buffer | String))`
typeTag `(Number)` the typeTag to use
secKey `((Buffer | String))`
nonce `((Buffer | String))`
Returns
`Promise<MutableData>`:
▸ newPublic(name, typeTag)
src/api/mutable.js

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

newPublic(name: any, typeTag: Number): Promise<MutableData>
Parameters
name `(any)`
typeTag `(Number)` the typeTag to use
Returns
`Promise<MutableData>`:
▸ newPermissions()
src/api/mutable.js

Create a new Permissions object.

newPermissions(): Promise<Permissions>
Returns
`Promise<Permissions>`:
▸ newPermissionSet()
src/api/mutable.js

Create a new PermissionsSet object.

newPermissionSet(): Promise<PermissionsSet>
Returns
`Promise<PermissionsSet>`:
▸ newMutation()
src/api/mutable.js

Create a new EntryMutationTransaction object.

newMutation(): Promise<EntryMutationTransaction>
Returns
`Promise<EntryMutationTransaction>`:
▸ newEntries()
src/api/mutable.js

Create a new Entries object.

newEntries(): Promise<Entries>
Returns
`Promise<Entries>`:
▸ fromSerial(serial)
src/api/mutable.js

Create a new Mutuable Data object from its serial

fromSerial(serial: any): Promise<MutableData>
Parameters
serial `(any)`
Returns
`Promise<MutableData>`:

## Immutable

### Reader

src/api/immutable.js

Hold the connection to read an existing ImmutableData

new Reader()

Extends helpers.NetworkObject

Instance Members
▸ read(options?)
src/api/immutable.js

Read the given amount of bytes from the network

read(options: Object?)
Parameters
options `(Object?)`

Name | Description
--- | ---
options.offset `Number` (default `0`) | start position
options.end `Number` (default `size`) | end position or end of data

▸ size()
src/api/immutable.js

The size of the mutable data on the network

size(): Promise<Number>
Returns
`Promise<Number>`: length in bytes

### Writer

src/api/immutable.js

Holds a immutable Data Writer

new Writer()

Extends helpers.NetworkObject

Example

    // write new data to the network
    app.immutableData.create().then((writer)=> {
     return writer.write("some string\n")
      .then(() => writer.write("second string"))
      .then(() => writer.close())
      .then((address) => app.immutableData.fetch(address)
        .then((reader) => reader.read()
          .then( (payload) => {
            should(payload).equals("some string\nsecond string");
          })
        ))
    })

Instance Members
▸ write(string)
src/api/immutable.js

Append the given data to immutable Data.

write(string: String): Promise<()>
Parameters
string `(String)` the data to write
Returns
`Promise<()>`:
▸ close(cipherOpt, the)
src/api/immutable.js

Close and write the immutable Data to the network.

close(cipherOpt: any, the: CipherOpt): Promise<String>
Parameters
cipherOpt `(any)`
the `(CipherOpt)` Cipher Opt to encrypt data with
Returns
`Promise<String>`: the address to the data once written to the network
▸ save()
src/api/immutable.js

Proxy to `close`.

save()

## Mutable

### MutableData

src/api/mutable.js

Holds the reference to a MutableData

new MutableData()

Extends h.NetworkObject

Instance Members
▸ quickSetup(data, name, description)
src/api/mutable.js

Easily set up a newly (not yet created) MutableData with the app having full-access permissions (and no other). The name and description parameters are metadata for the MutableData which can be used to identify what this MutablaData contains. The metadata is particularly used by the Authenticator when another application has requested mutation permissions on this MutableData, so the user can make a better decision to either allow or deny such a request based on this information.

quickSetup(data: Object, name: (String | Buffer), description: (String | Buffer)): Promise<MutableData>
Parameters
data `(Object)` a key-value payload it should create the data with
name `((String | Buffer))` a descriptive name for the MutableData
description `((String | Buffer))` a detailed description for the MutableData content
Returns
`Promise<MutableData>`: self
Example

    app.mutableData.newRandomPublic(tagtype)
      .then((md) => md.quickSetup({
           key1: 'value1',
           key2: 'value2'
         }, 'My MutableData', 'To store my app\'s data'))

▸ setMetadata(name, description)
src/api/mutable.js

Set the metadata information in the MutableData. Note this can be used only if the MutableData was already committed to the network, .i.e either with `put`, with `quickSetup`, or if it is an already existing MutableData just fetched from the network. The metadata is particularly used by the Authenticator when another application has requested mutation permissions on this MutableData, displaying this information to the user, so the user can make a better decision to either allow or deny such a request based on it.

setMetadata(name: (String | Buffer), description: (String | Buffer)): Promise
Parameters
name `((String | Buffer))` a descriptive name for the MutableData
description `((String | Buffer))` a detailed description for the MutableData content
Returns
`Promise`: resolves once finished
▸ encryptKey(key)
src/api/mutable.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.

encryptKey(key: (String | Buffer)): Promise<Key>
Parameters
key `((String | Buffer))` the key you want to encrypt
Returns
`Promise<Key>`: the encrypted entry key
▸ encryptValue(value)
src/api/mutable.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.

encryptValue(value: (String | Buffer)): Promise<Value>
Parameters
value `((String | Buffer))` the data you want to encrypt
Returns
`Promise<Value>`: the encrypted entry value
▸ decrypt(value)
src/api/mutable.js

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

decrypt(value: (String | Buffer)): Promise<Value>
Parameters
value `((String | Buffer))` the data you want to decrypt
Returns
`Promise<Value>`: the decrypted value
▸ getNameAndTag()
src/api/mutable.js

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

getNameAndTag(): Promise<NameAndTag>
Returns
`Promise<NameAndTag>`: the XoR-name and type tag
▸ getVersion()
src/api/mutable.js

Look up the mutable data object version on the network

getVersion(): Promise<Number>
Returns
`Promise<Number>`: current version
▸ get(key)
src/api/mutable.js

Look up the value of a specific key

get(key: any): Promise<ValueVersion>
Parameters
key `(any)`
Returns
`Promise<ValueVersion>`: the entry value and its current version
▸ put(permissions, entries)
src/api/mutable.js

Commit this MutableData to the network.

put(permissions: (Permission | null), entries: (Entries | null)): Promise
Parameters
permissions `((Permission | null))` the permissions to create the mutable data with
entries `((Entries | null))` data entries to create the mutable data with
Returns
`Promise`:
▸ getEntries()
src/api/mutable.js

Get a Handle to the entries associated with this MutableData

getEntries(): Promise<(Entries)>
Returns
`Promise<(Entries)>`: the entries representation object
▸ getKeys()
src/api/mutable.js

Get a Handle to the keys associated with this MutableData

getKeys(): Promise<(Keys)>
Returns
`Promise<(Keys)>`: the keys representation object
▸ getValues()
src/api/mutable.js

Get a Handle to the values associated with this MutableData

getValues(): Promise<(Values)>
Returns
`Promise<(Values)>`: the values representation object
▸ getPermissions()
src/api/mutable.js

Get a Handle to the permissions associated with this mutableData

getPermissions(): Promise<(Permissions)>
Returns
`Promise<(Permissions)>`: the permissions representation object
▸ getUserPermissions(signKey)
src/api/mutable.js

Get a Handle to the permissions associated with this MutableData for a specifc key If the signKey provided is `null` the permission set will be then assummed as `USER_ANYONE`.

getUserPermissions(signKey: (SignKey | null)): Promise<(Permissions)>
Parameters
signKey `((SignKey | null))` the key to look up
Returns
`Promise<(Permissions)>`: the permissions set associated to the key
▸ delUserPermissions(signKey, version)
src/api/mutable.js

Delete the permissions of a specifc key. Directly commits to the network. Requires 'ManagePermissions'-Permission for the app. If the signKey provided is `null` the permission set will be then assummed for `USER_ANYONE`.

delUserPermissions(signKey: (SignKey | null), version: Number): Promise
Parameters
signKey `((SignKey | null))` the key to lookup for
version `(Number)` the version successor, to confirm you are actually asking for the right one
Returns
`Promise`: once finished
▸ setUserPermissions(signKey, pmset, version)
src/api/mutable.js

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

setUserPermissions(signKey: (SignKey | null), pmset: PermissionSet, version: Number): Promise
Parameters
signKey `((SignKey | null))` the key to lookup for
pmset `(PermissionSet)` the permission set to set to
version `(Number)` the version successor, to confirm you are actually asking for the right one
Returns
`Promise`: resolves once finished
▸ applyEntriesMutation(mutations)
src/api/mutable.js

Commit the transaction to the network

applyEntriesMutation(mutations: EntryMutationTransaction): Promise
Parameters
mutations `(EntryMutationTransaction)` the Mutations you want to apply
Returns
`Promise`: resolves once finished
▸ serialise()
src/api/mutable.js

Serialise the current MutableData

serialise(): Promise<(String)>
Returns
`Promise<(String)>`: the serialilsed version of the MutableData
▸ emulateAs(eml)
src/api/mutable.js

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

emulateAs(eml: String): Emulation
Parameters
eml `(String)` name of the emulation
Returns
`Emulation`: the Emulation you are asking for

### Entries

src/api/mutable.js

Represent the Entries of a MutableData network object

new Entries()

Extends h.NetworkObject

Instance Members
▸ len()
src/api/mutable.js

Get the total number of entries in the MutableData

len(): Promise<Number>
Returns
`Promise<Number>`: number of entries
▸ get(keyName)
src/api/mutable.js

Look up the value of a specific key

get(keyName: String): Promise<ValueVersion>
Parameters
keyName `(String)` the key to lookup
Returns
`Promise<ValueVersion>`: the entry's value and the current version
▸ forEach(fn)
src/api/mutable.js

Iterate over the entries, execute the function for each item

forEach(fn: function (Buffer, ValueVersion)): Promise
Parameters
fn `(function (Buffer, ValueVersion))` the function to call
Returns
`Promise`: resolves once the iteration is done
▸ insert(keyName, value)
src/api/mutable.js

Insert a new entry. Once you call `MutableData.put` with this entry, it will fail if the entry already exists or the current app doesn't have the permissions to edit that mutable data.

insert(keyName: (String | Buffer), value: (String | Buffer)): Promise
Parameters
keyName `((String | Buffer))` the key you want store the data under
value `((String | Buffer))` the data you want to store
Returns
`Promise`: resolves once storing is done
▸ mutate()
src/api/mutable.js

Create a new mutation transaction for the entries

mutate(): Promise<EntryMutationTransaction>
Returns
`Promise<EntryMutationTransaction>`: the mutation transaction object

### Keys

src/api/mutable.js

Represent the keys of a MutableData network object

new Keys()

Extends h.NetworkObject

Instance Members
▸ len()
src/api/mutable.js

Get the total number of keys in the MutableData

len(): Promise<Number>
Returns
`Promise<Number>`: number of keys
▸ forEach(fn)
src/api/mutable.js

Iterate over the keys, execute the function for each entry.

forEach(fn: function (Buffer)): Promise
Parameters
fn `(function (Buffer))` the function to call with the key in the buffer
Returns
`Promise`: resolves once the iteration is done

### Values

src/api/mutable.js

Represent the values of a MutableData network object

new Values()

Extends h.NetworkObject

Instance Members
▸ len()
src/api/mutable.js

Get the total number of values in the MutableData

len(): Promise<Number>
Returns
`Promise<Number>`: number of values
▸ forEach(fn)
src/api/mutable.js

Iterate over the values, execute the function for each entry.

forEach(fn: function (Buffer, ValueVersion)): Promise
Parameters
fn `(function (Buffer, ValueVersion))` the function to call
Returns
`Promise`: resolves once the iteration is done

### EntryMutationTransaction

src/api/mutable.js

Holds a mutations to be done to the entries within one transaction on the network.

You need this whenever you want to change the content of the entries.

new EntryMutationTransaction()

Extends h.NetworkObject

Example

    // Mutate a range of Entries

    app.mutableData.newPublic(somename, tagtype)
     .then((mData) => mData.getEntries()
      .then((entries) => entries.mutate()
        .then((m) => m.insert('key', 'value')
          // this is where all mutations are recorded
          .then(() => mData.applyEntriesMutation(m))
        )))

Instance Members
▸ insert(keyName, value)
src/api/mutable.js

Store a new `Insert`-Action in the transaction to store a new entry.

insert(keyName: (String | Buffer), value: (String | Buffer)): Promise
Parameters
keyName `((String | Buffer))` the key you want to insert
value `((String | Buffer))` the value you want to insert
Returns
`Promise`: resolves once the storing is done
▸ remove(keyName, version)
src/api/mutable.js

Store a new `Remove`-Action in the transaction to remove an existing entry.

remove(keyName: (String | Buffer), version: Number): Promise
Parameters
keyName `((String | Buffer))` the key you want to remove
version `(Number)` the version successor, to confirm you are actually asking for the right version
Returns
`Promise`: resolves once the storing is done
▸ update(keyName, value, version)
src/api/mutable.js

Store a `Update`-Action in the transaction to update an existing entry.

update(keyName: (String | Buffer), value: (String | Buffer), version: Number): Promise
Parameters
keyName `((String | Buffer))` the key for 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 version
Returns
`Promise`: resolves once the storing is done

### MDataAction

src/native/_mutable.js

One of: `Insert`, `Update`, `Delete`, `ManagePermissions`

MDataAction

Type: String

### Permissions

src/api/mutable.js

Holds the permissions of a MutableData object

new Permissions()

Extends h.NetworkObject

Instance Members
▸ len()
src/api/mutable.js

Total number of permission entries

len(): Promise<Number>
Returns
`Promise<Number>`: number of entries
▸ getPermissionSet(signKey)
src/api/mutable.js

Lookup the permissions of a specifc key If the signKey provided is `null` the permission set will be then assumed to be `USER_ANYONE`.

getPermissionSet(signKey: (SignKey | null)): Promise<PermissionSet>
Parameters
signKey `((SignKey | null))` the key to lookup for
Returns
`Promise<PermissionSet>`: the permission set for that key
▸ insertPermissionSet(signKey, permissionSet, pmset)
src/api/mutable.js

Insert a new permission set mapped to a specifc key. Directly commits to the network. Requires 'ManagePermissions'-Permission for the app. If the signKey provided is `null` the permission set will be then set for `USER_ANYONE`.

insertPermissionSet(signKey: (SignKey | null), permissionSet: any, pmset: PermissionSet): Promise
Parameters
signKey `((SignKey | null))` the key to map to
permissionSet `(any)`
pmset `(PermissionSet)` the permission set to insert
Returns
`Promise`: once finished
▸ forEach(fn)
src/api/mutable.js

Iterate over the entries, execute the function provided for each of entry, and return a promise that resolves once iteration is finished.

forEach(fn: function (Buffer, ValueVersion)): Promise
Parameters
fn `(function (Buffer, ValueVersion))` the function to call
Returns
`Promise`: resolves once the iteration is done

### PermissionsSet

src/api/mutable.js

A Set of Permissions per Sign key. Each action might either be allowed or denied

new PermissionsSet()

Extends h.NetworkObject

Instance Members
▸ setAllow(action)
src/api/mutable.js

Set the action as allowed

setAllow(action: String): Promise
Parameters
action `(String)` the action to be set as allowed
Returns
`Promise`:
▸ setDeny(action)
src/api/mutable.js

Set the action as denied

setDeny(action: String): Promise
Parameters
action `(String)` the action to be set as denied
Returns
`Promise`:
▸ clear(action)
src/api/mutable.js

Remove action from the set

clear(action: String): Promise
Parameters
action `(String)` the action to clear permissions on
Returns
`Promise`:

## Emulations

Emulations and Abstractions on top of MData

### NFS

src/api/emulations/nfs.js

NFS Emulation on top of an MData

new NFS(mData: any)
Parameters
mData `(any)`
Instance Members
▸ create(content)
src/api/emulations/nfs.js

Helper function to create and save file to the network

create(content: (String | Buffer)): File
Parameters
content `((String | Buffer))` file contents
Returns
`File`: a newly created file
▸ fetch(fileName)
src/api/emulations/nfs.js

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

fetch(fileName: String): Promise<File>
Parameters
fileName `(String)` the path/file name
Returns
`Promise<File>`: the file found for that path
▸ insert(fileName, file)
src/api/emulations/nfs.js

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

insert(fileName: (String | Buffer), file: File): Promise<File>
Parameters
fileName `((String | Buffer))` the path to store the file under
file `(File)` the file to serialise and store
Returns
`Promise<File>`: the same file
▸ update(fileName, file, version)
src/api/emulations/nfs.js

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

update(fileName: (String | Buffer), file: File, version: Number): Promise<File>
Parameters
fileName `((String | Buffer))` the path to store the file under
file `(File)` the file to serialise and store
version `(Number)` the version successor number, to ensure you are overwriting the right one
Returns
`Promise<File>`: the same file
▸ delete(fileName, version)
src/api/emulations/nfs.js

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

delete(fileName: (String | Buffer), version: Number): Promise
Parameters
fileName `((String | Buffer))`
version `(Number)`
Returns
`Promise`:
▸ open(file, openMode)
src/api/emulations/nfs.js

Open a file for reading or writing.

Open modes (these constants are declared in ../../consts.js): OPEN_MODE_OVERWRITE: Replaces the entire content of the file when writing data. OPEN_MODE_APPEND: Appends to existing data in the file. OPEN_MODE_READ: Open file to read.

open(file: File, openMode: Number): Promise<File>
Parameters
file `(File)`
openMode `(Number = `OPEN_MODE_OVERWRITE`)`
Returns
`Promise<File>`:

### File

src/api/emulations/nfs.js

A NFS-style File

Note: As this application layer, the network does not check any of the metadata provided.

new File(ref: any, connection: any, fileCtx: any)
Parameters
ref `(any)`
connection `(any)`
fileCtx `(any)`
Instance Members
▸ dataMapName
src/api/emulations/nfs.js

The dataMapName to read the immutable data at

dataMapName
Returns
`Buffer`: XoR-name
▸ created
src/api/emulations/nfs.js

When was this created? in UTC.

created
Returns
`Date`:
▸ modified
src/api/emulations/nfs.js

When was this last modified? in UTC.

modified
Returns
`Date`:
▸ size()
src/api/emulations/nfs.js

Get file size

size(): Promise<Number>
Returns
`Promise<Number>`:
▸ read(position, len)
src/api/emulations/nfs.js

Read the file. FILE_READ_FROM_BEGIN and FILE_READ_TO_END may be used to read the entire content of the file. These constants are declared in ../../consts.js.

read(position: Number, len: Number): Promise<[Data, Size]>
Parameters
position `(Number)`
len `(Number)`
Returns
`Promise<[Data, Size]>`:
▸ write(fileContent, content)
src/api/emulations/nfs.js

Write file

write(fileContent: any, content: (Buffer | String)): Promise
Parameters
fileContent `(any)`
content `((Buffer | String))`
Returns
`Promise`:
▸ close()
src/api/emulations/nfs.js

Close file

close(): Promise
Returns
`Promise`:
▸ version
src/api/emulations/nfs.js

Which version was this? Equals the underlying MutableData's entry version.

version
Returns
`Number`:

## Types

### SignKey

src/api/crypto.js

Holds signature key

new SignKey()

Extends h.NetworkObject

Instance Members
▸ getRaw()
src/api/crypto.js

generate raw string copy of signature key

getRaw(): Promise<Buffer>
Returns
`Promise<Buffer>`:

### KeyPair

src/api/crypto.js

Holds an asymmetric keypair

new KeyPair(app: any, pub: any, secret: any)
Parameters
app `(any)`
pub `(any)`
secret `(any)`
Instance Members
▸ pubEncKey
src/api/crypto.js

get the Public Encryption key instance of this keypair

pubEncKey
Returns
`PubEncKey`:
▸ secEncKey
src/api/crypto.js

get the Secrect Encryption key instance of this keypair

secEncKey
Returns
`secEncKey`:
▸ decryptSealed(cipher)
src/api/crypto.js

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

decryptSealed(cipher: any): Promise<Buffer>
Parameters
cipher `(any)`
Returns
`Promise<Buffer>`: Plaintext

### SecEncKey

src/api/crypto.js

Holds the secret part of an encryption key

new SecEncKey()

Extends h.NetworkObject

Instance Members
▸ getRaw()
src/api/crypto.js

generate raw string copy of encryption key

getRaw(): Promise<Buffer>
Returns
`Promise<Buffer>`:
▸ decrypt(cipher, theirPubKey)
src/api/crypto.js

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

decrypt(cipher: any, theirPubKey: any): Promise<Buffer>
Parameters
cipher `(any)`
theirPubKey `(any)` {PubEncKey} the others public key
Returns
`Promise<Buffer>`: Plaintext

### PubEncKey

src/api/crypto.js

Holds the public part of an encryption key

new PubEncKey()

Extends h.NetworkObject

Instance Members
▸ getRaw()
src/api/crypto.js

generate raw string copy of encryption key

getRaw(): Promise<Buffer>
Returns
`Promise<Buffer>`:
▸ encryptSealed(str)
src/api/crypto.js

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

encryptSealed(str: any): Promise<Buffer>
Parameters
str `(any)`
Returns
`Promise<Buffer>`: Ciphertext
▸ encrypt(str, secretKey)
src/api/crypto.js

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

encrypt(str: any, secretKey: any): Promise<Buffer>
Parameters
str `(any)`
secretKey `(any)`
Returns
`Promise<Buffer>`: Ciphertext

### CipherOpt

src/api/cipher_opt.js

Holds the reference to a Cipher Options, either PlainText, Symmetric or Asymmetric

new CipherOpt()

Extends h.NetworkObject

### NameAndTag

src/api/mutable.js
NameAndTag

Type: Object

Parameters
name `(Buffer)` the XoR-name/address on the network
tag `(Number)` the type tag

### ValueVersion

src/api/mutable.js
ValueVersion

Type: Object

Parameters
buf `(Buffer)` the buffer with the value
version `(Number)` the version Holds the informatation of a value of a MutableData

### Emulation

src/api/emulations/index.js

Emulations are abstraction helpers on top of MData

Emulation

Type: NFS