search

joshuef / safe-js

12 stars 7 forks source link

readme

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="https://github.com/joshuef/safe-js/raw/master/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.

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.

isTokenValid

Check if an app token is valid.

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)

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)

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)

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)

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)

Returns a Promise which resolves truthy upon success.

createFile

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

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.

Returns a Promise which resolves truthy upon success.

deleteDir

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

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)

Returns a Promise which resolves truthy upon success.

getDir

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

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)

Returns a Promise which resolves to the response.

getFileMetadata

Get a file's metadata.

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

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)

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

Todo

License

MIT.