built.io-browserify/lib/presence.js

SDK for Built.io Backend which is compatible with Browserify

var R                     = require('ramda');
var when                  = require('when');
var utility               = require('./utilities/utility');
var instanceMethodBuilder = require('./utilities/instanceMethodBuilder')();
var Built                 = require('./built');

/**
* @class Presence
* @classdesc
* Presence is a feature that allows you to determine if a certain application user is currently online or offline. It stores the "last seen" timestamp of the user, which is useful in chat applications. Additionally, it allows you to store the "state" associated with the user's profile (e.g., users could use it to store chat statuses).
* @instance
* @description Represents presence details of a user. Instance of presence is retrieved every time a user fetches his or someone else's presence.
* @example
* // 'blt12sampleb09157' is uid of an Application user on Built.io Backend
* var user = app.User('blt12sampleb09157');
* user
* .getPresence()
* .then(function(presence){
*    // console.log(presence.getState());
* });
*/
var presenceCons = module.exports = R.curry(function(app,data) {
	var returnObj = {
		toJSON:function(){
			return data;
		},
		data   : data,
		app    : app
	}
	return instanceMethodBuilder.build(module.exports,returnObj);
});

/** Util methods **/
var getData  = R.prop('data');

function getMixinedData(presence){
	return R.mixin({},getData(presence));
}

var set = module.exports.set = R.curry(function(parameter,value,presence){
	var newData           = getMixinedData(presence);
	newData[parameter]    = value;
	return presenceCons(presence.app, newData);
});

/**
* You can enable/disable your presence using this function. Disable your presence if you don't want it to be broadcast, or its state to be set. This is similar to going "invisible".
* @function enable
* @instance
* @memberof Presence
* @param {Boolean} enable Set it to true to enable presence. Set to false for otherwise.
* @example
* var user = app.User('blt12sampleb09157');
* user
* .getPresence()
* .then(function(presence){
*    var newPresence = presence.enable(true);
* });
* @return {Presence}
*/

module.exports.enable = set('enabled');
instanceMethodBuilder.define('enable',2);

/**
* Gets the time when the user was last seen online
* @function getLastSeen
* @instance
* @memberof Presence
* @example
* var User = app.User;
* User
* .getCurrentUserPresence()
* .then(function(presence){
*    var lastSeen = presence.getLastSeen()
* });
* @return {Presence}
*/
module.exports.getLastSeen = function(presence){
	return presence.get('last_seen')
}
instanceMethodBuilder.define('getLastSeen',1);
/**
* Gets whether the user is online or offline
* @function getStatus
* @instance
* @memberof Presence
* @example
* User
* .getCurrentUserPresence()
* .then(function(presence){
*    var status = presence.getStatus()
* });
* @return {Presence}
*/
module.exports.getStatus = function(presence){
	return presence.get('status')
}
instanceMethodBuilder.define('getStatus',1);

/**
* Saves your presence details on the server
* @function save
* @instance
* @memberof Presence
* @example
* var user = app.User('blt12sampleb09157');
* user
* .getPresence()
* .then(function(presence) {
*    presence
*    .setWhiteList(['blt111sample01122', 'blt111sample01133'])
*    .setStatusMessage({
*       message: 'Hello'
*    })
*    .save()
*    .then(function(presence) {
*       console.log(presence.toJSON()); // updated presence details
*    });
* });
* @return {Promise<Presence>}
*/
module.exports.save = function(presence){
	return socketEmit('setPresence', getData(presence), presence);
}
instanceMethodBuilder.define('save',1);

var get = module.exports.get = R.curry(function(parameter,presence){
	return R.prop(parameter,getData(presence));
});
instanceMethodBuilder.define('get',2);

/**
* Checks whether the user's presence is enabled
* @function isEnabled
* @instance
* @memberof Presence
* @example
* var User = app.User;
* User
* .getCurrentUserPresence()
* .then(function(presence){
*    console.log(presence.isEnabled());
* });
* @return {Boolean}
*/
module.exports.isEnabled = get('enabled');
instanceMethodBuilder.define('isEnabled',1);

/**
* Gets the application user whose presence was broadcast
* When a user logs in, his presence is broadcast to all users who have requested for his presence updates. To know the user whose presence was updated, use this method.
* @function getApplicationUser
* @instance
* @memberof Presence
* @example
* var User = app.User;
* User.on('presence',function(presence){
*    console.log(presence.getApplicationUser());
* })
* @return {Boolean}
*/

module.exports.getApplicationUser = function(presence){
	return R.prop('application_user',getData(presence));
}
instanceMethodBuilder.define('getApplicationUser',1);

var socketEmit  = R.curry(function(string, payload, presence) {
	var app       = presence.app;
	var socket    = app.getSocket();
	var deferred  = when.defer();
	function emitFn(socket) {
		socket.emit(string, payload, function(err, data) {
			if (err) {
				deferred.reject(err);
			}
			if (!err && data)
				deferred.resolve(presenceCons(app, data.presence)); //server returns an object consisting a presence property
		});
	}
	if(app.isSocketConnected()){
		if (app.isSocketAuthStarted())
			app.getAdhocOperations().push(emitFn);
		else
			emitFn(app.getSocket());
	}else
		app.getAdhocOperations().push(emitFn);

	return deferred.promise;
});