Habitica

var Habitica = require('habitica')
var api = new Habitica({
  id: 'your-habitica.com-user-id',
  apiToken: 'your-habitica.com-api-token',
  endpoint: 'http://custom-url.com',
  platform: 'The Name of Your Integration'
  errorHandler: function (err) {
    // handle all errors from failed requests
  }
})

var Habitica = require('habitica')
var api = new Habitica()

var Habitica = require('habitica')

function sendNotification (style, message) {
  // logic for sending a notification to user
}

var api = new Habitica({
  id: 'your-habitica.com-user-id',
  apiToken: 'your-habitica.com-api-token',
  errorHandler: function (err) {
    if (err instanceof Habitica.ApiError) {
      // likely a validation error from
      // the API request
      sendNotification('warning', err.messsage)
    } else if (err instanceof Habitica.UnknownConnectionError) {
      // either the Habitica API is down
      // or there is no internet connection
      sendNotification('danger', err.originalError.message)
    } else {
      // there is something wrong with your integration
      // such as a syntax error or other problem
      console.error(err)
    }
  }
})

api.get('/tasks/id-that-does-not-exist').then(() => {
  // will never get here
  return api.get('/something-else')
}).then(() => {
  // will never get here
}).catch((err) => {
  // before this happens, the errorHandler gets run
  err // undefined because the errorHandler did not return anything
  // you could leave the catch off entirely since the
  // configured errorHandler does all the necessary work
  // to message back to the user
})

Methods

del(route, bodyopt, queryopt) → {Promise}

Parameters:

Source:

• index.js, line 301

Returns:

Type

Promise

Examples

A basic request

api.del('/tasks/the-task-id').then(() => {
  // The task has been deleted
})

Handling errors

api.del('/groups/the-group-id').then(() => {
 // The group has been deleted
}).catch((err) => {
  // handle errors
})

get(route, queryopt) → {Promise}

Parameters:

Source:

• index.js, line 201

Returns:

Type

Promise

Examples

Making a basic request

api.get('/user').then((res) => {
  var user = res.data

  user.profile.name // the user's display name
})

A request with a query Object

api.get('/groups', {
  type: 'publicGuilds,privateGuilds'
}).then((res) => {
  var guilds = res.data
  var guild = guilds[0]

  guild.name // the name of the group
})

Handling errors

api.get('/tasks/non-existant-id').then((res) => {
  // will never get here
}).catch((err) => {
  err.message // 'Task not found'
})

getOptions() → {Object}

Source:

• index.js, line 85

Returns:

Type

Object

localLogin(usernameOrEmail, password) → {Promise}

Parameters:

Source:

• index.js, line 158

Returns:

Type

Promise

Example

The id and api token will be set automatically after a sucessful login request

api.login('username or email','password').then((res) => {
  var creds = res.data

  creds.id // the user's id
  creds.apiToken // the user's api token
}).catch((err) => {
  // handle login errors
})

post(route, bodyopt, queryopt) → {Promise}

Parameters:

Source:

• index.js, line 238

Returns:

Type

Promise

Examples

A request with a body

api.post('/tasks/user', {
  text: 'Task Name',
  notes: 'Task Notes',
  type: 'todo'
}).then((res) => {
  var task = res.data

  task.text // 'Task Name'
})

Handling errors

api.post('/groups', {
  type: 'party',
  name: 'My Party'
}).then((res) => {
  var party = res.data

  party.name // 'My Party'
}).catch((err) => {
  // handle errors
})

put(route, bodyopt, queryopt) → {Promise}

Parameters:

Source:

• index.js, line 274

Returns:

Type

Promise

Examples

A request with a body

api.put('/tasks/the-task-id', {
  text: 'New Task Name',
  notes: 'New Text Notes'
}).then((res) => {
  var task = res.data

  task.text // 'New Task Name'
})

Handling errors

api.put('/groups/the-group-id', {
  name: 'New Group Name'
}).then((res) => {
  var group = res.data

  group.name // 'New Group Name'
}).catch((err) => {
  // handle errors
})

register(username, email, password) → {Promise}

Parameters:

Source:

• index.js, line 126

Returns:

Type

Promise

Example

The id and api token will be set automatically after a sucessful registration request

api.register('username', 'email', 'password').then((res) => {
  var user = res.data
}).catch((err) => {
  // handle registration errors
})

setOptions(options)

Parameters:

Source:

• index.js, line 107

Example

api.setOptions({
  id: 'new-user-id',
  apiToken: 'new-api-token',
  endpoint: 'http://localhost:3000/',
  platform: 'Great-Habitica-Integration',
  errorHandler: yourErrorHandlerFunction
})