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
• cbox.destroy
• cbox.friends
  • cbox.friends.add
  • cbox.friends.feed
  • cbox.friends.remove
• cbox.messages
  • cbox.messages.broadcast
  • cbox.messages.feed
  • cbox.messages.list
  • cbox.messages.read
• cbox.peer
  • cbox.peer.get
  • cbox.peer.set
• cbox.peers
  • cbox.peers.feed
  • cbox.peers.gc
  • cbox.peers.get
  • cbox.peers.set

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

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

Contribute

Feel free to dive in! Open an issue or submit PRs.

License

MIT © Alan Shaw