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), 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.

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

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Last publish

Collaborators

`authorise`

`isTokenValid`

`addService`

`createLongName`

`listLongNames`

`listServices`

`createDir`

`createFile`

`createOrUpdateFile`

`deleteDir`

`deleteFile`

`getDir`

`getFile`

`getFileMetadata`

`rename`

`renameDir`

`renameFile`

Weekly Downloads