Typescript/Javascript client for Textile's Powergate.
Use Powergate's multi-tiered file storage API built on Filecoin and IPFS from javascript environments such as Node, React Native, web browsers, and more.
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.
npm i @textile/powergate-client
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 })Most Powergate APIs require authorization in the form of a user auth token. Users are created using the admin API. Powergate's backend may be configured to secure the admin API with an auth token, and in that case, you'll neeed to set the admin auth token on the client as shown below.
import { createPow } from "@textile/powergate-client"
const host = "http://0.0.0.0:6002" // or whatever powergate instance you want
const pow = createPow({ host })
// Set the admin auth token if required.
pow.setAdminToken("<an admin auth token>")
async function exampleCode () {
const { user } = await pow.admin.users.create() // save this token for later use!
return user?.token
}The returned auth token is the only thing that gives access to the corresponding user at a later time, so be sure to save it securely.
A user auth token can later be set for the Powergate client so that the client authenticates with the user associated with the auth token.
import { createPow } from "@textile/powergate-client"
const host = "http://0.0.0.0:6002" // or whatever powergate instance you want
const pow = createPow({ host })
const token = "<previously generated user auth token>"
pow.setToken(token)Now, all authenticated APIs are available for you to use.
import fs from "fs"
import { createPow, powTypes } from "@textile/powergate-client"
const host = "http://0.0.0.0:6002" // or whatever powergate instance you want
const pow = createPow({ host })
async function exampleCode() {
// get wallet addresses associated with the user
const { addressesList } = await pow.wallet.addresses()
// create a new address associated with the user
const { address } = await pow.wallet.newAddress("my new address")
// get build information about the powergate server
const res = await pow.buildInfo()
// cache data in IPFS in preparation to store it
const buffer = fs.readFileSync(`path/to/a/file`)
const { cid } = await pow.data.stage(buffer)
// store the data using the default storage configuration
const { jobId } = await pow.storageConfig.apply(cid)
// watch the job status to see the storage process progressing
const jobsCancel = pow.storageJobs.watch((job) => {
if (job.status === powTypes.JobStatus.JOB_STATUS_CANCELED) {
console.log("job canceled")
} else if (job.status === powTypes.JobStatus.JOB_STATUS_FAILED) {
console.log("job failed")
} else if (job.status === powTypes.JobStatus.JOB_STATUS_SUCCESS) {
console.log("job success!")
}
}, jobId)
// watch all log events for a cid
const logsCancel = pow.data.watchLogs((logEvent) => {
console.log(`received event for cid ${logEvent.cid}`)
}, cid)
// get information about the latest applied storage configuration,
// current storage state, and all related Powegate storage jobs
const { cidInfo } = await pow.data.cidInfo(cid)
// retrieve data stored in the user by cid
const bytes = await pow.data.get(cid)
// send FIL from an address managed by the user to any other address
await pow.wallet.sendFil(addressesList[0].address, "<some other address>", BigInt(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.
You can read the generated API docs to see the available Powergate API.
PRs accepted.
Small note: If editing the README, please conform to the standard-readme specification.
MIT (c) 2020 Textile