Websocket API

Request Socket Token

Socket tokens are like session tokens, except they can only be used to authenticate a socket connection. They also expire quickly, and must be used within 5 minutes of obtaining it.

GET /api/socket

Example Request:

curl -X GET \
  -H "Authorization: bearer <token>" \
  https://nitro-server.herokuapp.com/api/socket

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "socketToken": "<token>"
}

Connect with SockJS and Jandal

Connections are given three seconds to send the 'user.auth' message before they are disconnected.

jandal = new Jandal()
sock = new SockJS("https://nitro-server.herokuapp.com/socket");
jandal.connect(sock);
jandal.on('socket.open', function () {
  console.log('we are online');
  jandal.emit('user.auth', socketToken, function (err) {
    if (err) return console.log('error authorizing");
    console.log('successfully authorized socket');
  });
});

Messages

user.auth(token, callback)

If authorization is successful, err will be null and status will be true.

If authorization fails, err will contain the error message and status will be null.

jandal.emit('user.auth', socketToken, function (err, status) {
  if (err) {
    console.log('could not authorize connection - try another socketToken');
  } else {
    console.log('connection is now authorized');
  }
});

user.info(callback)

Returns user information

Parameters:

• callback : returns the user information.

Example Request:

jandal.emit('user.info', function (err, info) {
  console.log(info);
});

Example Response:

[null, {
  "id": 2,
  "name": "sam",
  "email": "crazycheese@gmail.com",
  "pro": false,
  "createdAt": "2014-01-04T29:58:34.448Z"
}]

task.read(callback)

Get all the tasks.

Parameters:

• callback : returns the tasks

Example Request:

jandal.emit('task.read', function (err, tasks) {
  console.log(tasks);
});

Example Response:

[null, [
  {
    "id": 32,
    "userId": 2,
    "listId": 12,
    "name": "Fix all the bugs",
    "notes": "",
    "date": 1392781001,
    "priority": 2,
    "completed": 0
  },
  { ... }
]]

task.create(data, callback)

Create a task. Returns the task id.

Parameters:

• data : the task data. Should not contain id or userId.
• callback : returns the task id.

Example Request:

var task = {
  listId: 30,
  name: 'my task',
  notes: '',
  date: 0,
  priority: 1,
  completed: 0
};

jandal.emit('task.create', task, function (err, task) {
  console.log('created task with id', task.id);
});

Example Response:

[null, {
  "id": 21,
  "userId": 2,
  "listId": 30,
  "name": "my task",
  "notes": "",
  "date": 0,
  "priority:" 1,
  "completed": 0
}]

task.update(id, data, [callback])

Update an existing task.

Parameters:

• id : the task id
• data : the changes to make to the task
• [callback] : optional callback. Returns the updated task.

data can contain any task property, except id, listId or userId.

If you want to change the list a task is in, use task.move.

Example Request:

var id = 42;

var changes = {
  name: 'I changed the name of the task'
};

jandal.emit('task.update', id, changes, function (err, task) {
  console.log('full task', task);
});

Example Response:

[null, {
  "id": 42,
  "userId": 2,
  "listId": 30,
  "name": "I changed the name of the task",
  "notes": "",
  "date": 0,
  "priority": 1,
  "completed": 0
}]

task.move(taskId, listId, [callback])

Move a task to another list.

Parameters:

• taskId : the task id
• listId : the list id
• [callback] : an optional callback. Returns the updated task.

Example Request:

var taskId = 21;
var listId = 42;

jandal.emit('task.move', taskId, listId, function (err, task) {
  console.log(task);
});

Example Response:

[null, {
  "id": 21,
  "userId": 2,
  "listId": 42,
  "name": "the task name",
  "notes": "",
  "date": 0,
  "priority": 1,
  "completed": 0
}]

task.destroy(id, [callback])

Destroy a task.

Parameters:

• id : the task id
• [callback] : an optional callback. Return true.

Example Request:

jandal.emit('task.destroy', 42, function (err, success) {
  console.log('destroyed the task');
});

Example Response:

[null, true]

list.read(callback)

Get all the lists.

Parameters:

• [callback] : returns the lists

Example Request:

jandal.emit('list.read', function (err, lists) {
  console.log(lists);
});

Example Response:

[null, [
  {
    "id": 20,
    "userId": 2,
    "name": "Inbox"
  },
  { ... }
]]

list.create(data, callback)

Create a list.

Parameters:

• data : the list data. Should not include id or userId.
• [callback] : returns the list

Example Request:

var list = {
  name: "Shopping List"
};

jandal.emit('list.create', list, function (err, id) {
  console.log('created a new list with the id', id);
});

Example Response:

[null, {
  "id": 21,
  "userId": 2,
  "name": "Shopping List"
}]

list.update(id, data, [callback])

Update an existing list.

Parameters:

• id : the list id
• data : the changes to make to the list
• [callback] : optional callback

data can contain any list property except id or listId.

Example Request:

var id = 21;

var changes = {
  name: 'Renamed the list'
};

jandal.emit('list.update', id, changes, function (err, list) {
  console.log(changes);
});

Example Response:

[null, {
  "id": 21,
  "userId": 2,
  "name": "Renamed the list"
}]

list.destroy(id, [callback])

Destroy an existing list.

jandal.emit('list.destroy', id, function (err, success) {
  console.log('deleted list');
});

Example Response:

[null, true]

Prefs

Format:

{
  "sort": unsigned int,
  "night": unsigned int,
  "language": string - length 5,
  "weekStart": unsigned int,
  "dateFormat": string - length 7,
  "moveCompleted": unsigned int,
  "confirmDelete": unsigned int
}

pref.update(data, [callback])

Update a preference. You can change any setting.

var changes = {
  "night": 0,
  "confirmDelete": 1
};

jandal.emit('pref.update', changes, function (err, prefs) {
  console.log(prefs);
});

Example Response:

[null, {
  "sort": 1,
  "night": 0,
  "language": "en-us",
  "weekStart": 1,
  "dateFormat": "dd/mm/yy",
  "moveCompleted": 0,
  "confirmDelete": 1
}]

Queue

queue.sync(data, clientTime, callback)

Send an array of events. This is useful for handling changes made while the client is offline.

clientTime is the time on the client in seconds. It is used to account for timezone differences between the server and the client.

clientTime = Math.floor(Date.now() / 1000)

A callback is required. The server returns an export of the all the tasks, lists and prefs owned by the user.

jandal.emit('queue.sync', queue, clientTime, function (err, data) {
  console.log('tasks', data.task);
  console.log('lists', data.list);
  console.log('prefs', data.pref);
});

Example Response:

[null, {
  "list": [

  ],
  "task": [

  ],
  "pref": {

  }
}]