SAFE-js

Isomorphic adaptation of API hooks found in the safe demo app.

Built using isomorphic-fetch, to work in node or in the browser.

Currently still in beta. YMMV. Please report any issues. Pull requests are entirely welcome for features and documentation.

Use

Grab it

npm i safe-js --save

And use it

import * as safe from 'safe-js';

Available methods are taken from the demo app, and docs (which are currently not up to date) live here: https://maidsafe.readme.io/docs/introduction .

safe.nfs safe.dns safe.auth structuredData appendableData dataId cipherOpts signKey

are objects available for use.

Alternatively you can access these same methods in the [Safe Beaker Browser (SBB)] (https://github.com/joshuef/beaker/), via window.safeAuth, window.safeNFS and window.DNS;

Polyfill

safe-js has a polyfill to create window.safeXXX functionality when it's not available (non safe:// sites in SAFE Beaker Browser, for eg. ).

You can simply include this file in the <head> of your page during development and continue using the APIs as they are provided by Safe Beaker Browser.

<head>
  <title>safejs site not yet on the network!</title>
  <!-- replace this link with the actual polyfill location -->
  <script src="./safe-js/dist/polyfill.js" ></script>            
</head>

Examples

Auth (window.safeAuth methods in the SAFE browser):

import { auth } from 'safe-js';
import packageData from '../package.json'

const LOCAL_STORAGE_TOKEN_KEY = 'BOOM';

const app =
{
    name: "name",
    id: "id",
    version: "v",
    vendor: "vendor_name",
    permissions: ["SAFE_DRIVE_ACCESS"]
};

auth.authorise( app );

getFile:

import { nfs } from 'safe-js';
nfs.createFile(token, 'primaryIndex.json', {} ,false, APP_DIR);

API

auth.js

(window.safeAuth methods in the SAFE browser)

`authorise`

Authorise the app with the SAFE launcher.

packageData - Object containing your app information. This is how the application will authorised in the launcher.

eg:

let app = {
   name: '',
   id: '',
   version: '',
   vendor: '',
   permissions: [],
  }
  
safeAuth.authorise( app )

Promise Return

Returns an object of the form:

{
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6Im5RT1poRFJ2VUFLRlVZMzNiRTlnQ25VbVVJSkV0Q2lmYk4zYjE1dXZ2TlU9In0.OTKcHQ9VUKYzBXH_MqeWR4UcHFJV-xlllR68UM9l0b4",
    "permissions": [
        "SAFE_DRIVE_ACCESS"
    ]
}

If the current token was valid, permissions will be omitted.

tokenKey - string to ID the auth token in localStorage

`isTokenValid`

Check if an app token is valid.

token - Auth token string.

Returns a promise, which returns a boolean of validity.

dns.js

(window.safeDNS methods in the SAFE browser)

`addService`

Creates a SAFE DNS Service. (https://api.safedev.org/dns/add-service.html)

token - (string) - auth token
longName - longName to add service to.
serviceName - Name of service to create.
serviceHomePathDir - The full path of the directory to be served by this service.
isPathShared - Name of service to create

Returns a promise which resolves as truthy upon success.

`createLongName`

Creates a SAFE DNS LongName / Public Id. (https://api.safedev.org/dns/create-long-name.html)

token - (string) - auth token
longName - Name of service to create

Returns a promise which resolves as truthy upon success.

`listLongNames`

List all long names registered by current user (https://api.safedev.org/dns/list-long-names.html)

token - (string) - auth token

Returns a JSON array of long names.

[
    "example",
    "test"
]

`listServices`

List all services associated with a long name registered by current user (https://api.safedev.org/dns/list-services.html)

token - (string) - auth token

Returns a JSON array of service names.

[
    "www",
    "test"
]

nfs.js

(window.safeNFS methods in the SAFE browser)

`createDir`

(https://api.safedev.org/nfs/directory/create-directory.html)

token - (string) auth token
dirPath - (string) full directory path
isPrivate - (bool) is the data private?
metadata - (base64 string) metadata for the dir.
isPathShared - (bool) true if writing to the sharedDRIVE, false writes to APP;

Returns a Promise which resolves truthy upon success.

`createFile`

(https://api.safedev.org/nfs/file/create-file.html)

token - (string) auth token
filePath - (string) file path
dataToWrite - data of file being uploaded
dataType - (string - optional), type of data being uploaded. text/plain for example.
dataLength - (int - optional) length of data being written.
metadata - (base64 string - optional) metadata for the dir.
isPathShared - (bool - optional) true if writing to the sharedDRIVE, false writes to APP;

Returns a Promise which resolves truthy upon success.

`createOrUpdateFile`

Helper function to make or update a file as no current method exists to do this in the SAFE API at this point.

Either creates a file if it doesn't exist, or deletes and recreates with the new content if it does already exist.

token - (string) auth token
filePath - (string) file path
dataToWrite - data of file being uploaded
dataType - (string - optional), type of data being uploaded. text/plain for example.
dataLength - (int - optional) length of data being written.
metadata - (base64 string - optional) metadata for the dir.
isPathShared - (bool - optional) true if writing to the sharedDRIVE, false writes to APP;

Returns a Promise which resolves truthy upon success.

`deleteDir`

(https://api.safedev.org/nfs/directory/delete-directory.html)

token - (string) auth token
dirPath - (string) file path
isPathShared - (bool - optional) true if writing to the sharedDRIVE, false writes to APP;

Returns a Promise which resolves truthy upon success.

TODO? Remove isPathShared here and use only path string ( which would include app/drive?)

`deleteFile`

(https://api.safedev.org/nfs/file/delete-file.html)

token - (string) auth token
filePath - (string) file path
isPathShared - (bool - optional) true if writing to the sharedDRIVE, false writes to APP;

Returns a Promise which resolves truthy upon success.

`getDir`

(https://api.safedev.org/nfs/directory/get-directory.html)

token - (string) auth token
dirPath - (string) file path
isPathShared - (bool - optional) true if writing to the sharedDRIVE, false writes to APP;

Returns a Promise which resolves to a JSON object of dir info.

{
    "info": {
        "name": "images",
        "isPrivate": true,
        "createdOn": "2016-09-26T04:41:05.342Z",
        "modifiedOn": "2016-09-26T04:41:05.342Z",
        "metadata": "c2FtcGxlIG1ldGFkYXRh"
    },
    "files": [],
    "subDirectories": []
}

`getFile`

Get a file.

(https://api.safedev.org/nfs/file/get-file.html)

token - (string) auth token
filePath - (string) file path
responseParsing - (string) type of response parsing to return. Defaults to text, can be buffer,blob,json or false, which would simply return the response.
isPathShared - (bool - optional) true if writing to the sharedDRIVE, false writes to APP;

Returns a Promise which resolves to the response.

`getFileMetadata`

Get a file's metadata.

(https://api.safedev.org/nfs/file/get-file.html)

token - (string) auth token
filePath - (string) file path
isPathShared - (bool - optional) true if writing to the sharedDRIVE, false writes to APP;

Returns a Promise which resolves to the response headers upon success.

`rename`

Rename a file or dir.

(https://api.safedev.org/nfs/directory/update-directory.html) (https://api.safedev.org/nfs/file/update-file.html)

token - (string) auth token
path - (string) path
newName - (string) new name
isFile - (bool) true if it is a file and not a dir.
metadata - (base64 string - optional) metadata for the dir.
isPathShared - (bool - optional) true if writing to the sharedDRIVE, false writes to APP;

Returns a Promise which resolves truthy upon success.

`renameDir`

(https://api.safedev.org/nfs/directory/update-directory.html)

Wrapper for rename with directory options set. Returns a Promise which resolves truthy upon success.

`renameFile`

(https://api.safedev.org/nfs/file/update-file.html)

Wrapper for rename with file options set. Returns a Promise which resolves truthy upon success.

TODO

NFS needs move endpoints

Todo

Add auth.js documentation.
Add dns.js documentation.
Add nfs.js documentation.
Improve documentation (clarity/readability/gitbook?).
Increase test coverage.
Ensure all API endpoints are represented.
Update isPathShared to appOrDrive ? ... Something more semantic.

License

MIT.

joshuef/safe-js

SAFE-js

Use

Polyfill

Examples

API

auth.js

authorise

Promise Return

isTokenValid

dns.js

addService

createLongName

listLongNames

listServices

nfs.js

createDir

createFile

createOrUpdateFile

deleteDir

deleteFile

getDir

getFile

getFileMetadata

rename

renameDir

renameFile

TODO

Todo

License

`authorise`

`isTokenValid`

`addService`

`createLongName`

`listLongNames`

`listServices`

`createDir`

`createFile`

`createOrUpdateFile`

`deleteDir`

`deleteFile`

`getDir`

`getFile`

`getFileMetadata`

`rename`

`renameDir`

`renameFile`