molekilla / fdp-storage-old

Fair Data Protocol Storage

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.

Table of Contents

• Install
  • npm
  • Use in Node.js
  • Use in a browser with browserify, webpack or any other bundler
  • Use in a browser Using a script tag
• Usage
• API
• Contribute
  • Setup
  • Test
• License

Install

npm

> npm install @fairdatasociety/fdp-storage --save

yarn

> yarn add @fairdatasociety/fdp-storage

Use in Node.js and browser

We require Node.js's version of at least 16.x

const FDP = require('@fairdatasociety/fdp-storage');

Use in a browser Using a script tag

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>

Usage

Creating FDP account

import { FdpStorage } from '@fairdatasociety/fdp-storage'

const fdp = new FdpStorage('http://localhost:1633', 'http://localhost:1635')
const wallet = fdp.account.createWallet() // after creating a wallet, the user must top up its balance before registration
const account = 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) // prints list of user's pods

Sharing a pod

const shareReference = await fdp.personalStorage.share('my-new-pod')
console.log(shareReference) // prints share reference of a pod

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

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')

Migrate from v1 to v2 account

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
})

Documentation

You can generate API docs locally with:

npm run docs

The generated docs can be viewed in browser by opening ./docs/index.html

Contribute

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!

Setup

Install project dependencies with

npm ci

Test

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

Compile code

In order to compile NodeJS code run

npm run compile:node

or for Browsers

npm run compile:browser

Maintainers

• nugaon
• IgorShadurin

License

BSD-3-Clause