This document is work in progress
Install the module to your project:
npm install orbit_
And require it in your program:
const Orbit = require('orbit_')Please note that Orbit requires you to pass an instance of IPFS to its constructor. You can create and IPFS instance with js-ipfs or js-ipfs-api or you can use a higher-level wrapper that does everything automatically for you, like ipfs-daemon.
Create an instance of Orbit.
ipfs - An IPFS instance. Either js-ipfs or js-ipfs-api.
options - Default options are:
{
keystorePath: <path>, // path where to keep keys
cacheFile: <file>, // path to orbit-db cache file
maxHistory: 64 // how many messages to retrieve from history on joining a channel
}
Usage
const orbit = new Orbit(ipfs)Returns the current user.
Usage
const user = orbit.user
console.log(user.name, user.id)Returns the network info.
Usage
const network = orbit.network
console.log(network.name) // 'Orbit DEV Network'Returns the channels the user is currently joined on.
Returns a list of IPFS swarm peers.
Connect to a network as username.
TODO: return value, thrown errors, example
Usage
orbit.events.on('connected', (network) => {
console.log(`Connected to ${network.name} as ${orbit.user.name}`)
})
orbit.connect('Haad')Disconnect from the currently connected network.
TODO: return value, thrown errors, example
Usage
orbit.disconnect()Join a channel. Upon successfully joining a channel, events will emit 'joined' event.
Returns true if joined a channel, false if orbit is already joined on the channel.
Usage
orbit.events.on('joined', (channel) => console.log(`Joined #${channel}`))
orbit.join('mychannel')Or
orbit.join('mychannel')
.then((channel) => console.log(`Joined #${channel}`))Leave a channel.
TODO: return value, thrown errors, example
orbit.leave()Send a message to a channel. Channel must be joined first.
TODO: return value, thrown errors, example
orbit.events.on('message', (channel, message) => console.log(message))
orbit.send('mychannel', 'hello world')To get the actual content of the message, you need to get the POST from message.payload.value with:
orbit.getPost(message.payload.value)
.then((post) => console.log(post))
/*
{
content: 'hello world',
...
}
*/Get messages from a channel. Returns a Promise that resolves to an Array of messages.
TODO: params, thrown errors, example
Get the contents of a message.
If withUserProfile is set to false, the post will NOT include the user information in post.meta.from but rather the id (IPFS hash) of the user. This is the same as calling getPost and then calling getUser as in the example below.
TODO: params, return value, thrown errors, example
orbit.getPost(message.payload.value)
.then((post) => {
console.log(`${post.meta.ts} < ${post.meta.from.name}> ${post.content}`)
})Or
orbit.getPost(message.payload.value, false)
.then((post) => {
// Get the user info
orbit.getUser(post.meta.from)
.then((user) => {
console.log(`${post.meta.ts} < ${user.name}> ${post.content}`)
})
})Get user profile.
orbit.getUser(post.meta.from)
.then((user) => {
console.log(`${user.id} - ${user.name}`)
})Add a file to a channel. Source is an object that defines how to add the file.
Returns a FilePost object.
Source object:
addFile(channel, source) where source is:
{
// for all files, filename must be specified
filename: <filepath>, // add an individual file
// and optionally use one of these in addition
directory: <path>, // add a directory
buffer: <Buffer>, // add a file from buffer
// optional meta data
meta: <meta data object>
}FilePost:
{
name: 'File1',
hash: 'Qm...File1',
size: 123,
from: 'Qm...Userid',
meta: { ... }
}Usage:
orbit.addFile(channel, { filename: "file1.txt" }) // add single file
orbit.addFile(channel, { filename: "test directory", directory: filePath }) // add directory
orbit.addFile(channel, { filename: "file1.txt", buffer: new Buffer(<file1.txt as Buffer>) }) // add a buffer as fileGet contents of a file from Orbit. Returns a stream. Takes a hash of the file as an argument.
orbit.getFile('Qm...File1')
.then((stream) => {
let buf = new Uint8Array(0)
stream.on('data', (chunk) => {
const appendBuffer = new Uint8Array(buf.length + chunk.length)
appendBuffer.set(buf)
appendBuffer.set(chunk, buf.length)
buf = appendBuffer
})
stream.on('error', () => /* handle error */)
stream.on('end', () => /* the Stream has finished, no more data */)
})
.catch((e) => console.error(e))Returns a directory listing as an Array
orbit.getDirectory('Qm...Dir1')
.then((result) => {
// result is:
// {
// Hash: 'Qm...Dir1,
// Size: 18,
// Type: ..., // Type === 1 ? "this is a directory" : "this is a file"
// Name: 'Dir1'
// }
})