vox-client

Postvox client library

This is a client library for the Postvox network. The package also includes a(n awful) terminal client for the network.

• Using vox-client
  • VoxClient methods
    • new VoxClient(options)
    • VoxClient.connect() -> Promise
    • VoxClient.subscribe(stream) -> Promise
    • VoxClient.unsubscribe(stream) -> Promise
    • VoxClient.listSubscriptions() -> Promise>
    • `VoxClient.post(message
    • VoxClient.postVote(stanza) -> Promise
    • VoxClient.postUserStatus(stanza) -> Promise
    • VoxClient.postUserProfile(stanza) -> Promise
    • VoxClient.createReadStream(options) -> stream.Readable
    • VoxClient.createCheckpointStream(options) -> stream.Transform
    • VoxClient.close()
• Terminal client

Using vox-client

Fetch the library with NPM:

$ npm install vox-client vox-common

Use it:

var VoxClient = require('vox-client')
var voxurl = require('vox-common/voxurl')
 
var client = new VoxClient({
    agentString: 'My client agent',
    nick: 'myclientnickname'
})
 
client.connect()
  .then(function() {
    client.post({ text: 'Hello!' })
  })

VoxClient methods

new VoxClient(options)

Creates a new VoxClient.

Options fields

Name	Type	Details
options.nick	String	The Postvox nickname to use. Must have been registered with the network. The nickname's credentials must be accessible from options.profilesDir or options.config. Use vox init --nick <nickname> to register a new nickname with the network. Defaults to --nick.
options.profilesDir	String	If set, then read profile configs and store the local databases in this directory. Defaults to --profilesDir if set, or ~/.voxprofiles otherwise.
options.config	Object	If set, then use this config object instead of reading from disk.
options.config.nick	String	The Postvox nickname to use. Required if config is given.
options.config.privkey	String	The user's private key in RSA PEM format. Required if config is given.
options.config.interchangeUrl	String	The URL to the user's home interchange server. Required if config is given.
hubUrl	String	The Hub url to use. Defaults to --hubUrl if set, or http://hub.postvox.net otherwise.
agentString	String	The agent to send to servers. Defaults to 'voxbot :)'.

VoxClient.connect() -> Promise

Initialized the client object and connects to the interchange servers for any saved subscriptions.

Must be called before any other operations.

VoxClient.subscribe(stream) -> Promise

Subscribes the user to the given stream. The subscription is saved locally, and will be restored for future connections.

If any read streams are open, the new subscription will be added to those streams.

stream must be a valid stream identifier: '[vox:]<nickname>[/streamname]' or '@<nickname>[/streamname]'. The following are valid stream identifiers:

• vox:spacemaus
• vox:spacemaus/friends
• @spacemaus
• @spacemaus/friends
• spacemaus
• spacemaus/friends

VoxClient.unsubscribe(stream) -> Promise

Does the opposite of .subscribe(stream).

VoxClient.listSubscriptions() -> Promise<Array<Subscription>>

Returns an array of the user's locally-saved subscriptions.

VoxClient.post(message[, options]) -> Promise<Message>

Posts a message to a stream.

Message fields

Name	Type	Details
stream	String	The stream to post the message to. See .subscribe() for valid stream names.
text	String	The text of the message.
title	String	A title for the message.
userUrl	String	A URL to publish with the message
etc	Object	Miscellaneous payload. Will be JSON encoded, if present.
replyToStanza	Message	If set, then the message is a reply to this Message stanza. The message's stream, replyTo, and thread fields will be set accordingly, and it will be cloned to the appropriate streams.

Options fields

Name	Type	Details
cloneToMentions	bool	If true, the message will be cloned to the servers of any nicknames that were "@mentioned" in the message's text. Defaults to true.

VoxClient.postVote(stanza) -> Promise<Vote>

Posts a vote to a stream.

Stanza fields

See Vote stanza.

VoxClient.postUserStatus(stanza) -> Promise<UserStatus>

Posts a user status to a stream.

Stanza fields

See UserStatus stanza.

VoxClient.postUserProfile(stanza) -> Promise<UserProfile>

Posts a user profile to a stream.

Stanza fields

See UserProfile stanza.

VoxClient.createReadStream(options) -> stream.Readable

Creates a Readable stream for one or more Postvox streams.

Options fields

Name	Type	Details
type	String	If given, only stanzas of this type will be read. One of 'MESSAGE', 'USER_STATUS', 'USER_PROFILE', 'VOTE'.
stream	String	If given, only stanzas posted to this stream will be read. If not given, then all subscribed streams will be read.
seqStart	int	If given, the stream will start reading from the stanza with this seq value. If this value is not specified, then the stream will only return stanzas received after this Readable stream is created. If negative, the stream will start from that number of most-recent stanzas (e.g., seqStart: –20 starts from the 20th most recent stanza).
seqLimit	int	If given, the stream will stop reading just before the stanza with this seq value.
checkpointKey	String	A key used to load stream checkpoints. Overrides seqStart, if the checkpoint is in the database.
batchMode	bool	If true, then the stream will return arrays of stanzas. If false, the stream will return single stanzas.
batchSize	int	The target size of batches to fetch from the database/network.

VoxClient.createCheckpointStream(options) -> stream.Transform

Creates a Transform stream that writes checkpoints for the stanzas that pass through it.

Options fields

Name	Type	Details
checkpointKey	String	The key to use to write stream checkpoints to the local database.

VoxClient.close()

Closes the client and any connections.

Terminal client

$ npm install -g vox-client
$ vox init --nickname <mynickname>
# Follow instructions to register a new nickname

$ vox --nickname <mynickname>
> :help