sleepless-users

Generic, server-side, user account and session handling API.

This module implements an API that interfaces with the Sleepless global user account REST API. In order to use this, you need a client ID and client secret, which are only available from Sleepless Software Inc.

This is not browser code.

Install

npm install sleepless-users

Setup

Load the module:

su = require( "sleepless-users" )

In order to get an API object, call the connect() function to establish a connection using a client ID and secret:

opts = { client_id: "FOO", client_secret: "BAR" };

su.connect( opts, api => {
	api.authenticate( { username, password }, session => {
		// do stuff
	} );
}, fail );

This library uses the okay/fail callback convention where the last two arguments are callback functions, okay() and fail() respectively. If all goes well, okay() is called with the results, otherwise, fail is called with some kind of explanatory error information. Most of the functions in this library use this same convention.

For the connect() function, okay will be called with an API object that you then use to do everything else.

Register User Account

api.register( { username: "foo", password: "bar", data: { ... }  }, () => {
	...
}, fail )

If the new account is registered, okay() is called. Otherwise, fail() is called with an error message.

The 'data' is any JSON.stringify()'able thing which will be stored with the user record.

Login/Authenticate

Once an account has been registered, then you can create a session with authenticate():

api.authenticate( { username: "foo", password: "bar" }, sid => {
	...
}, fail )

This call authenticates against the registered users with the given user/pass. On success, okay will be called with a session id, which is a random string that uniquely identifies the session.

Get Session Object

To get a session object given an SID, do this:

api.get_sesssion( sid, session => {
	...
}, fail );

On success, okay() is called with a session object which contains session info, and some methods for doing things specific to the session.

Freshen Session

session.freshen( okay, fail )

This "freshens" the session by resetting the timeout for the given session ID. If the session is still valid, okay() will be called, otherwise fail() will be called with an error message.

You would typically call this on user activity to keep the session alive.

IMPORTANT NOTE: The only way to keep a session alive currently, is to call this function.

End Session

session.end( () => {
	// session.sid is no longer valid
}, fail )

Deletes the session and makes the session ID invalid.

This function always calls okay() upon completion.

Get User Object

session.get_user( user => {
	...
}, fail )

Gets a user object associated with the session. This contains the username, and other useful information as well as more methods for doing things related to the user.

Fetch User Data

user.get_data( data => {
	...
}, fail )

Retrieves the generic data object associated with the user account. This is the data that was originally stored when the account was registered, or whatever data object was stored by the last call to user.set_data() (see below)

If successful, okay() is called with the object. On failure (such as the session ID being invalid), fail() is called.

Store User Data

user.set_data( new_data, () => {
	...
}, fail )

Stores a new generic data object with a user account. If successful, okay() is called. On failure (such as the session ID being invalid), fail() is called.

Example

See the file test.js for an example of how the API is called.