Chatterbox-core NPM

Chatterbox Core

The core API for Chatterbox, a messaging application built on IPFS and libp2p.

Install

npm install chatterbox-core

Usage

const Chatterbox = require('chatterbox-core')

API

Constructor

To create a new chatterbox core instance, await on a call to the factory function that is the default export for the module. Note a "ready" IPFS instance is required with pubsub enabled.

const Chatterbox = require('chatterbox-core')
const cbox = await Chatterbox(ipfs, [options])

ipfs: IPFS
options: Object
- repoDir: String (default /.chatterbox)
- topics: Object
  - broadcast: String (default /chatterbox/broadcast)
  - beacon: String (default /chatterbox/beacon)
- friendsMessageHistorySize: Number (default 1000)
- beaconInterval: Number (default 5 * 60 * 1000)

`cbox.destroy()`

Destroy the chatterbox instance.

Returns

Promise

`cbox.friends`

Manage friends.

`cbox.friends.add(peerId, [details])`

Parameters

peerId: String
details: Object
- name: String
- avatar: String

Returns

Promise

`cbox.friends.feed([options])`

Live updating friend list. Same output as cbox.peers.feed except all peers are friends.

Parameters

options: Object
- signal: AbortSignal
- filter: Function

Returns

AsyncIterable<Object[]>

for await (const friends of cbox.friends.feed())
  friends.forEach(peerInfo => console.log(peerInfo))

`cbox.friends.remove(peerId)`

Parameters

peerId: String

Returns

Promise

`cbox.messages`

Manage messages received from peers.

`cbox.messages.broadcast(text)`

Send a message to all peers connected to the chatterbox network. Note: this is a temporary PoC API call!

Parameters

text: String

Returns

Promise

`cbox.messages.feed(peerId, [options])`

Live updating list of messages for a given peer.

Parameters

peerId: String
options: Object
- signal: AbortSignal

Returns

AsyncIterable<Object[]>

for await (const list of cbox.messages.feed('Qm...'))
  list.forEach(msg => console.log(msg))

Each message:

id: String
text: String
receivedAt: Number
readAt: Number

`cbox.messages.list(peerId)`

Get the messages stored for a given peer.

Parameters

peerId: String

Returns

Promise<Object[]>

Each message:

id: String
text: String
receivedAt: Number
readAt: Number

`cbox.messages.read(peerId, messageId)`

Set the readAt field for a given message to the current time (if not already set).

Parameters

peerId: String
messageId: String

Returns

Promise

`cbox.peer`

`cbox.peer.get()`

Get the local peer's info.

Returns

Promise<Object>

id: String
name: String
avatar: String
lastSeenAt: Number
lastMessage: Object
- text: String
- receivedAt: Number
- readAt: Number

`cbox.peer.set(details)`

Set the peer's info.

Parameters

details: Object
- name: String
- avatar: String

Returns

Promise

`cbox.peers`

Information about peers in the chatterbox network.

`cbox.peers.feed([options])`

Live updating list of known peers in the chatterbox network.

Parameters

options: Object
- filter: Function
- signal: AbortSignal

Returns

AsyncIterable<Object[]>

for await (const list of cbox.peers.feed())
  list.forEach(peerInfo => console.log(peerInfo))

Each peer info:

id: String
name: String
avatar: String
lastSeenAt: Number
lastMessage: Object
- id: String
- text: String
- receivedAt: Number
- readAt: Number
isFriend: Boolean

`cbox.peers.gc([options])`

Clean up peers. Pass an optional filter function.

Parameters

options: Object
- filter: Function (default: collect peers last seen more than an hour ago that are not friends and are not the local peer)

Returns

Promise

`cbox.peers.get(peerId)`

Get details stored for the passed Peer ID.

Parameters

peerId: String

Returns

Promise<Object>

Peer details:

id: String
name: String
avatar: String
lastSeenAt: Number
lastMessage: Object
- id: String
- text: String
- receivedAt: Number
- readAt: Number
isFriend: Boolean

`cbox.peers.set(peerId, details)`

Set properties for a peer.

Parameters

peerId: String
details: Object
- name: String
- avatar: String
- lastSeenAt: Number
- lastMessage: Object
  - id: String
  - text: String
  - receivedAt: Number
  - readAt: Number
- isFriend: Boolean

MFS layout

/.chatterbox
├── peers
|   ├── QmPeer0
|   |   ├── info.json      # Peer info object
|   |   └── messages.json  # Array of received messages
|   ├── QmPeer1
|   └── QmPeer2
└── version.json  # Data store layout version

`peers/Qm.../info.json`

Peer data.

{
  "id": "QmPeerId",
  "name": "Dave",
  "avatar": "http://ipfs.io/ipfs/QmAvatar",
  "lastSeenAt": 1568883407737,
  "lastMessage": {
    "id": "HexMessageId",
    "text": "Hello World!",
    "receivedAt": 1568883407737,
    "readAt": 1568883407737
  },
  "isFriend": false
}

`peers/Qm.../messages.json`

Length limited messages received by a peer. Stored by receivedAt in ascending order.

[
  {
    "id": "HexMessageId",
    "text": "Hello World!",
    "receivedAt": 1568883407737,
    "readAt": 1568883407737
  }
]

Ideas

Message index file messages/index.json and then per message file as id (messages/[id].json) or receivedAt time (messages/1568883407737.json).
ndjson messages file messages.ndjson for streaming