Skip to content

joshuef/safe-js

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

115 Commits
docs/examples
docs/examples
 
 
src
src
 
 
test
test
 
 
.babelrc
.babelrc
 
 
.gitignore
.gitignore
 
 
.npmignore
.npmignore
 
 
.publishrc
.publishrc
 
 
.travis.yml
.travis.yml
 
 
CHANGELOG.md
CHANGELOG.md
 
 
README.md
README.md
 
 
karma.conf.js
karma.conf.js
 
 
package.json
package.json
 
 
webpack.config.js
webpack.config.js
 
 

Repository files navigation

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.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

12 stars

Watchers

5 watching

Forks

7 forks
Report repository

Releases

30 tags

Packages

No packages published

Contributors 6

Languages