Isomorphic adaptation of API hooks found in the safe demo app.
Built using isomorphic-fetch so it should work in node or in the browser.
Currently super-alpha. Limited tests done so far, but auth and create file endpoints work. This is currently mostly a learning project for the SAFE api.
If it's useful and you find problems (you will), PRs are welcome!
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
;
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>
Auth:
import * as safe 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"]
};
safe.utils.authorise( app );
getFile:
safe.nfs.createFile(token, 'primaryIndex.json', {} ,false, APP_DIR);
Authorise the app with the SAFE launcher. If a tokenKey
is passed it will check for an existing token in localstorage, if a valid key is found, it will
packageData
- Object containing your app information. This is how the application will authorised in the launcher.tokenKey
- Optional string to ID the returned auth token in localStorage (SAfe browser will overwrite this with its own storage token)
eg:
let app = {
name: '',
id: '',
version: '',
vendor: '',
permissions: [],
}
safeAuth.authorise( app )
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.
Returns the token stored at tokenKey
in localStorage
tokenKey
- string to ID the auth token in localStorage
Returns the longName stored at LongNameKey
in localStorage
LongNameKey
- string to ID the long name key in localStorage
Check if an app token is valid.
token
- Auth token string.
Returns a promise, which returns a boolean of validity.
Saves the token stored at tokenKey
in localStorage
Saves the userLongName stored at longNameKey
in localStorage
Creates a SAFE DNS Service. (https://api.safedev.org/dns/add-service.html)
token
- (string
) - auth tokenlongName
- longName to add service to.serviceName
- Name of service to create.isPathShared
- Name of service to createserviceHomePathDir
- The full path of the directory to be served by this service.
Returns a promise which resolves as truthy upon success.
Creates a SAFE DNS LongName / Public Id. (https://api.safedev.org/dns/create-long-name.html)
token
- (string
) - auth tokenlongName
- Name of service to create
Returns a promise which resolves as truthy upon success.
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"
]
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"
]
(https://api.safedev.org/nfs/directory/create-directory.html)
token
- (string
) auth tokendirPath
- (string
) full directory pathisPrivate
- (bool
) is the data private?metadata
- (base64 string
) metadata for the dir.isPathShared
- (bool
)true
if writing to the sharedDRIVE
,false
writes toAPP
;
Returns a Promise which resolves truthy upon success.
(https://api.safedev.org/nfs/file/create-file.html)
token
- (string
) auth tokenfilePath
- (string
) file pathdataToWrite
- data of file being uploadeddataType
- (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 toAPP
;
Returns a Promise which resolves truthy upon success.
(https://api.safedev.org/nfs/directory/delete-directory.html)
token
- (string
) auth tokendirPath
- (string
) file pathisPathShared
- (bool
- optional)true
if writing to the sharedDRIVE
,false
writes toAPP
;
Returns a Promise which resolves truthy upon success.
TODO? Remove isPathShared here and use only path string ( which would include app/drive?)
(https://api.safedev.org/nfs/file/delete-file.html)
token
- (string
) auth tokenfilePath
- (string
) file pathisPathShared
- (bool
- optional)true
if writing to the sharedDRIVE
,false
writes toAPP
;
Returns a Promise which resolves truthy upon success.
(https://api.safedev.org/nfs/directory/get-directory.html)
token
- (string
) auth tokendirPath
- (string
) file pathisPathShared
- (bool
- optional)true
if writing to the sharedDRIVE
,false
writes toAPP
;
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": []
}
Get a file.
(https://api.safedev.org/nfs/file/get-file.html)
token
- (string
) auth tokenfilePath
- (string
) file pathisPathShared
- (bool
- optional)true
if writing to the sharedDRIVE
,false
writes toAPP
;
Returns a Promise which resolves to the file data upon success.
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 tokenpath
- (string
) pathnewName
- (string
) new nameisFile
- (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 toAPP
;
Returns a Promise which resolves truthy upon success.
(https://api.safedev.org/nfs/directory/update-directory.html)
Wrapper for rename
with directory options set. Returns a Promise which resolves truthy upon success.
(https://api.safedev.org/nfs/file/update-file.html)
Wrapper for rename
with file options set. Returns a Promise which resolves truthy upon success.
- NFS needs
move
endpoints
- 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.
MIT.