cube-client

Node.js module that wraps the cube HTTP API in a client for ease of development

Usage

Install

$ npm i cube-client --save

var cube = require('cube-client')

To call API methods that require authentication, pass the account info to the exported function:

var cube = require('cube-client')(account)

API

cube.createAccount (opts, cb)

Creates a new Cube account, which has a monetary balance that can be used to pay for pinning refs. opts should contain the following:

{
  card: {
    number: '4242424242424242', // credit card Number
    exp: '01/20',               // expiration date
    cvc: 123                    // security code
  }
}

The result returned to cb will be the newly created account. This object can be passed into the function returned by require('cube-client') to access the authorized API methods using this account.

{
  "id": "4Gadp2zSX1dbT3", // user id
  "key": "Vms/N2vryD4kMQOHntJyzLklELdFdy72ZBgW8JPup/Y=" // secret API key
}

cube.getRefInfo (hash, cb)

Gets metadata about an IPFS ref pinned by Cube. hash should be a string containing the multihash of the ref, or a full IPFS path (/ipfs/HASH). Output will be in the following format:

{
  "ipfsPath": "/ipfs/Qmb3oW6u6M61QyMcJ4oSnKcFpLNdT9dyLiPGEkBuDmjLwC",
  "hash": "Qmb3oW6u6M61QyMcJ4oSnKcFpLNdT9dyLiPGEkBuDmjLwC",
  "size": 3479,
  "createdAt": 1444967924195,
  "updatedAt": 1444967931843,
  "bandwidthCredit": 1000000000,
  "bandwidthUsed": 3895,
  "storageCredit": 52185,
  "expiration": 1445831924195,
  "parents": [],
  "private": false,
  "child": null,
  "encrypted": false
}

cube.ipfsAdd (data, [opts], cb)

Requires a running IPFS daemon

Adds data to the local IPFS daemon. data can be a single value or array of file path strings, Buffers, or vinyl files. opts may contain the following:

{
  recursive: true, // adds children of a directory recursively, defaults to false
  stream: true, // return a stream of the IPFS daemon's output, rather than parsed JSON. defaults to false
  encrypt: true, // enables encryption, defaults to false
  key: 'hunter2' // passphrase or key to use for encryption
}

If the encrypt option is set to true, the added data will be combined into a tarball and encrypted using SHA-256-CTR. The key option can be a string passphrase which will be used to derive the key using pbkdf2 with 5000 iterations, or can be a 32-byte Buffer which will be used directly.

An object containing the parsed IPFS daemon output will be passed to cb (unless the stream option was set to true):

[
  {
    "Name": "lib/constants.js",
    "Hash": "QmceXhje7S6PLWuguvNXc2cbAuQjBZBsZL8Vsjv9Yn3SS4"
  },
  {
    "Name": "lib/",
    "Hash": "QmcmAHjHNa4EU5xVaH9wVR9CZ3E4mdfkVbAWnXPQ2YLfWq"
  }
]

cube.ipfsGet (ipfsPath, [opts], cb)

Requires a running IPFS daemon

Gets data from the local IPFS daemon and saves it to the local filesystem. ipfsPath should be something like /ipfs/<HASH> or /ipfs/<HASH>/foo/bar. opts may contain the following:

{
  output: './catPicture.jpg', // specify a path for the output file. defaults to the IPFS hash, in the current directory
  stream: true, // outputs a stream of the file contents rather than saving to the filesystem
}

cube.ipfsDaemon (cb)

Requires a running IPFS daemon

Gets the IPFS API client being used internally by Cube. When getting the client, Cube's IPFS daemon will be added as a swarm peer.

Authenticated methods

To use the following methods, you must be authenticated using your Cube account ID and secret API key. These can be created with cube.createAccount() (shown above), and passed to the exported 'cube-client' function:

var cube = require('cube-client')({
  "id": "4Gadp2zSX1dbT3",
  "key": "Vms/N2vryD4kMQOHntJyzLklELdFdy72ZBgW8JPup/Y="
})

Requests will be authenticated by setting HTTP headers containing the account id and a SHA-256 HMAC using the API KEY as the shared secret. Timestamps and nonces will also be added to requests.

cube.pin (opts, cb)

Pins a ref to Cube. If already pinned, adds resources to the existing pin. opts should contain the following:

{
  hash: 'QmcmAHjHNa4EU5xVaH9wVR9CZ3E4mdfkVbAWnXPQ2YLfWq', // can also contain a full IPFS path (/ipfs/HASH)
  bandwidth: 100, // total download bandwidth to make available, in MB
  storage: 365, // amount of time to keep the file pinned, in days
  private: false, // add these resources privately, defaults to false
  encrypted: false // specify whether this data is encrypted (currently does not do anything, but is stored on the server). defaults to false
}

Refs will be pinned until they hit their expiration date, and are made accessible through the Cube IPFS node and at http://cube.ipfs.io/ipfs/REF_HASH. If the bandwidth credit is fully consumed, the Cube gateway will return HTTP 402 - Payment Required on requests to the hash. Pinned ref metadata is accessible through cube.getRefInfo or through http://cube.ipfs.io/refs/REF_HASH.

cube.deposit (amount, cb)

Deposit into the balance of this account. Creates a charge to the credit card filed on this account. amount should be an integer amount of USD cents, which must be >= to cube.constants.minTransaction.

cube.account (cb)

Gets information about this account. Response is in the following format:

{
  key: <Buffer>, // API key as a Buffer
  balance: 99993799467755, // current account balance, in trillionths (1e-12) of a USD
  id: '4Gadp2zSX1dbT3' // account ID
}