aiswaryawalter / js-powergate-client

Typescript/Javascript client for Textile's Powergate

Powergate JS Client (@textile/powergate-client)

Typescript/Javascript client for Textile's Powergate.

Use Powergate's multitiered file storage API built on Filecoin and IPFS from javascript environments such as Node, React Native, web browsers, and more.

Table of Contents

• Powergate JS Client (@textile/powergate-client)
  • Background
  • Install
  • Usage
  • API
  • Maintainers
  • Contributing
  • License

Background

The Powergate JS Client is built on top of the Powergate gRPC APIs and contains the logic that makes it straight-forward to build those APIs into JavaScript-based systems. Using the Powergate JS Client requires access to a running instance of the Powergate. Find details on setting up the Powergate here.

The JS Client provides access to the full Powergate API and therefore, does not directly manage access-control. If you plan to use the Powergate JS Client in user-facing systems, we recommend running additional middleware.

Install

npm i @textile/powergate-client

Usage

Start by creating an instance of the client.

import { createPow } from "@textile/powergate-client"

const host = "http://0.0.0.0:6002" // or whatever powergate instance you want

const pow = createPow({ host })

Many APIs are immediately available and don't require authorization.

const { status, messageList } = await pow.health.check()

const { peersList } = await pow.net.peers()

Other APIs require authorization. The main API you'll interact with is the Filecoin File System (FFS), and it requires authorization. First, create a new FFS instance.

const { token } = await pow.ffs.create() // save this token for later use!

Currently, the returned auth token is the only thing that gives you access to your FFS instance at a later time, so be sure to save it securely.

Once you have an auth token, either by creating a new FFS instance or by reading one you previously saved, set the auth token you'd like the Powergate client to use.

pow.setToken(authToken)

Now, the FFS API is available for you to use.

import fs from "fs"
import { ffsTypes } from "@textile/powergate-client"

// get wallet addresses associated with your FFS instance
const { addrsList } = await pow.ffs.addrs()

// create a new address associated with your ffs instance
const { addr } = await pow.ffs.newAddr("my new addr")

// get general info about your ffs instance
const { info } = await pow.ffs.info()

// cache data in IPFS in preparation to store it using FFS
const buffer = fs.readFileSync(`path/to/a/file`)
const { cid } = await pow.ffs.addToHot(buffer)

// store the data in FFS using the default storage configuration
const { jobId } = await pow.ffs.pushConfig(cid)

// watch the FFS job status to see the storage process progressing
const cancel = pow.ffs.watchJobs((job) => {
  if (job.status === ffsTypes.JobStatus.CANCELED) {
    console.log("job canceled")
  } else if (job.status === ffsTypes.JobStatus.FAILED) {
    console.log("job failed")
  } else if (job.status === ffsTypes.JobStatus.SUCCESS) {
    console.log("job success!")
  }
}, jobId)

// watch all FFS events for a cid
const cancel = pow.ffs.watchLogs((logEvent) => {
  console.log(`received event for cid ${logEvent.cid}`)
}, cid)

// get the current desired storage configuration for a cid (this configuration may not be realized yet)
const { config } = await pow.ffs.getCidConfig(cid)

// get the current actual storage configuration for a cid
const { cidinfo } = await pow.ffs.show(cid)

// retreive data from FFS by cid
const bytes = await pow.ffs.get(cid)

// senf FIL from an address managed by your FFS instance to any other address
await pow.ffs.sendFil(addrsList[0].addr, "<some other address>", 1000)

See the Node.js example app in this repository's examples directory.

There are also several useful examples included in the *.spec.ts files of this repo.

API

You can read the generated API docs to see the available Powergate API.

Maintainers

Textile

Contributing

See the contributing file!

PRs accepted.

Small note: If editing the README, please conform to the standard-readme specification.

License

MIT (c) 2020 Textile