Typescript implementation of https://github.com/fairDataSociety/fairOS-dfs
Warning: This project is in beta state. There might (and most probably will) be changes in the future to its API and working. Also, no guarantees can be made about its stability, efficiency, and security at this stage.
npm install @fairdatasociety/fdp-storage
yarn add @fairdatasociety/fdp-storage
We require Node.js's version of at least 16.x
const FDP = require('@fairdatasociety/fdp-storage');
Loading this module through a script tag will make the fdp
object available in the global namespace.
<script src="https://unpkg.com/@fairdatasociety/fdp-storage/dist/index.browser.min.js"></script>
FDP Storage is ready to work with React Native. But a few shims need to be added to the initialization script of your project to make the library components work.
import 'react-native-url-polyfill/auto' // for bee-js. URL polyfill
import 'react-native-get-random-values' // for ethers.js cryptography
import '@ethersproject/shims' // commong shims for ethers.js
import 'text-encoding' // for fdp-storage to make TextEncoding work
Creating FDP account
import { FdpStorage } from '@fairdatasociety/fdp-storage'
const batchId = 'GET_BATCH_ID_FROM_YOUR_NODE' // fill it with batch id from your Bee node
const fdp = new FdpStorage('http://localhost:1633', batchId)
const wallet = fdp.account.createWallet() // after creating a wallet, the user must top up its balance before registration
await fdp.account.register('myusername', 'mypassword')
Login with FDP account
const wallet = await fdp.account.login('otherusername', 'mypassword')
console.log(wallet) // prints downloaded and decrypted wallet
Creating a pod
const pod = await fdp.personalStorage.create('my-new-pod')
console.log(pods) // prints info about created pod
Getting list of pods
const pods = await fdp.personalStorage.list()
console.log(pods.getPods()) // prints list of user's pods
console.log(pods.getSharedPods()) // prints list of pods that a user has added to their account
Sharing a pod
const shareReference = await fdp.personalStorage.share('my-new-pod')
console.log(shareReference) // prints share reference of a pod
Getting information about shared pod
await fdp.personalStorage.getSharedInfo(shareReference)
Saving shared pod under user's account
await fdp.personalStorage.saveShared(shareReference)
Creating a directory
await fdp.directory.create('my-new-pod', '/my-dir')
Deleting a directory
await fdp.directory.delete('my-new-pod', '/my-dir')
Uploading data as a file into a pod
await fdp.file.uploadData('my-new-pod', '/my-dir/myfile.txt', 'Hello world!')
Deleting a file from a pod
await fdp.file.delete('my-new-pod', '/my-dir/myfile.txt')
Sharing a file from a pod
const shareReference = await fdp.file.share('my-new-pod', '/my-dir/myfile.txt')
console.log(shareReference) // prints share reference of a file
Get information about shared file
await fdp.file.getSharedInfo(shareReference)
Save shared file to a pod
await fdp.file.saveShared('my-new-pod', '/', shareReference)
Getting list of files and directories with recursion or not
// with recursion
const list = await fdp.directory.read('my-new-pod', '/', true)
// without recursion
await fdp.directory.read('my-new-pod', '/')
console.log(list) // prints list of files and directories
Downloading data from a file path
const data = await fdp.file.downloadData('my-new-pod', '/myfile.txt')
console.log(data.text()) // prints data content in text format 'Hello world!'
Deleting a pod
await fdp.personalStorage.delete('my-new-pod')
Export old wallet with mnemonic
const wallet = await fdp.account.exportWallet('oldusername', 'oldpassword', {
mnemonic: 'one two three one two three one two three one two three'
})
or with address
const wallet = await fdp.account.exportWallet('oldusername', 'oldpassword', {
address: '0x...'
})
// ask user to top up his account, then can be started the migration process
await fdp.account.migrate('oldusername', 'oldpassword', {
mnemonic: wallet.mnemonic.phrase
})
You can generate API docs locally with:
npm run docs
The generated docs can be viewed in browser by opening ./docs/index.html
There are some ways you can make this module better:
- Consult our open issues and take on one of them
- Help our tests reach 100% coverage!
Install project dependencies with
npm ci
The tests run in both context: Jest and Puppeteer.
To run the integration tests, you need to use our bee-factory
project. Clone the repo, you can use our prebuilt Docker images with setting .env variables.
Customize .env values based on which FairOS version you want to run. After the .env variables are set use the ./scripts/environment.sh
script with start --fairos
parameter.
There are browser tests by Puppeteer, which also provide integrity testing.
npm run test:browser
The test HTML file which Puppeteer uses is the test/testpage/testpage.html.
To open and manually test FDP with developer console, it is necessary to build the library first with npm run compile:browser
(running the browser tests npm run test:browser
also builds the library).
In order to compile NodeJS code run
npm run compile:node
or for Browsers
npm run compile:browser
With specific system environment variables you can alter the behaviour of the tests.
BEE_API_URL
- API URL of Bee clientBEE_DEBUG_API_URL
- Debug API URL of Bee clientBEE_BATCH_ID
- Batch ID for data uploading