Flowdock Streaming client for node.js. Listen to messages from Flowdock in real-time and post new messages.
npm install flowdock
or
# in package.json
"dependencies": {
"flowdock": "latest"
}
Note that Flowdock.Session will emit errors, and if unhandled they will crash your application. If you want to just handle errors in the callbacks, attach an empty error handler to the instance.
var session = new Session(...);
session.on('error', function () { /* noop */ });The library supports authenticating using both the API token or a username and password.
var Session = require('flowdock').Session;
// For API token auth...
var s = new Session('deadbeefacdcabbacd')
// ...or using email/password combination
var s = new Session('[email protected]', 'mypassword')
Flow IDs are strings and should be considered opaque identifiers. Some older flows still have an id that looks human readable, but you should not try to parse any information from it, since it might no longer be accurate. If you need to create URLs, use flow.parameterized_name and flow.organization.parameterized_name.
var Session = require('flowdock').Session;
var session = new Session(email, password);
var stream = session.stream('6f67fd0b-b764-4661-9e53-c38293d1e997');
stream.end();The argument(s) for stream() can be a string ('6f67fd0b-b764-4661-9e53-c38293d1e997') or an array (['6f67fd0b-b764-4661-9e53-c38293d1e997', 'ba0a8850-bb05-42c4-a215-16bfece679e8']).
The second parameter can be used to add parameters to the streaming URL, meaning you can subscribe to private messages, for example. See Flowdock Streaming API documentation for more information about the available parameters.
var streamWithPrivates = session.stream('6f67fd0b-b764-4661-9e53-c38293d1e997', {user: 1, active: 'idle'});session.stream() returns an instance of EventEmitter. Currently it emits two types of events:
erroris emitted with a response status code and an error message. This can happen when a connection can't be estabilished or you don't have access to one or more flows that you tried to stream.messageis emitted when thestreamreceives a JSON message.
stream = session.stream(flowId);
stream.on('message', function(message) {
// Do stuff with message
return stream.end();
});The full message format specification for different message types is in Flowdock API Message documentation.
Session has several methods to send messages to Flowdock. All methods except status support adding tags to the messages. You can optionally supply a callback as the last parameter, with the signature -> (err, message, res), where message is the created message and res is the raw response object.
session.message('6f67fd0b-b764-4661-9e53-c38293d1e997', 'Isn\'t this cool?', ['tag1', 'tag2']);The first two arguments should be strings. The first argument is the flow ID and the second one is the message. The third argument is an optional array of tags. Sending a message is flow-specific.
session.comment('6f67fd0b-b764-4661-9e53-c38293d1e997', 54321, 'I\'m commenting through the api!', ['cool'])The first argument is the flow ID and the second is the ID of the message being commented. The rest of the arguments work the same as with message.
session.status('6f67fd0b-b764-4661-9e53-c38293d1e997', 'I just got the first message through the Flowdock streaming API.');Both arguments should be strings. The first argument is the flow ID and the second one is the status message. Setting a status is flow-specific.
session.privateMessage(12345, 'Hi, this is a secret message!');The first argument is the recipient's ID and the second one is the message.
// Note that flow and organization ids must be the "parameterized_name" from api response.
session.invite('my-flow', 'example-organization', '[email protected]', 'Please join our flow!');The first argument is flow ID, the second one is the organization ID, the third one is the invitation recipient's email address and the fourth is the custom message that is sent with the invitation.
When editing a message, you need to specify the organization, flow and message id of the edited message. You can then change the content or tags by supplying them in the data hash.
session.editMessage(
'my-flow',
'example-organization',
12345,
{content: 'new content'},
function (err, message, response) {
/* do something */
}
)session.flows(function(err, flows) {
var anotherStream, flowIds;
flowIds = flows.map(function(f) {
return f.id;
});
anotherStream = session.stream(flowIds);
return anotherStream.on('message', function(msg) {
console.log('message from stream:', msg);
// variable 'msg' being something like:
// {
// event: 'activity.user',
// flow: '6f67fd0b-b764-4661-9e53-c38293d1e997',
// content: { last_activity: 1329310503807 },
// user: '12345',
// .. plus few other fields
// }
});
});The full message format specification for different message types is in the Flowdock API Message documentation.
The Session object can be used as an API wrapper. It provides the basic HTTP request functions (GET, POST, PUT, DELETE). All functions accept the same parameters: path, data and callback. For example, fetching a single flow by ID:
session.get(
'/flows/find',
{id: '6f67fd0b-b764-4661-9e53-c38293d1e997'},
function (err, flow, response) {
/* do something */
}
);Or delete a message:
path = flow.url + "/messages/" + message.id;
session.delete(path, function (err) {
/* do something */
});Run npm install. Code can be compiled to .js with command make build.
- v. 0.9.1 - Removed buffertools dependency and now uses event.EventEmitter instead of process.EventEmitter. (Thanks @valeriangalliat)
- v. 0.9.0 - Updated dependencies to newest versions and added api wrappers (get, post, put, delete). Node 0.6 is no longer supported.
- v. 0.8.2 - Newer buffertools to support node 0.11
- v. 0.8.1 - Errors are error objects instead of strings. Flows callback also receives error as first argument.
- v. 0.8.0 - Message callbacks conform to node standard with -> (err, body, res) signature