rtm-api
Version:
Remember the Milk API Interface
669 lines (551 loc) • 20.8 kB
HTML
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>user/tasks.js - Documentation</title>
<script src="scripts/prettify/prettify.js"></script>
<script src="scripts/prettify/lang-css.js"></script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
<input type="checkbox" id="nav-trigger" class="nav-trigger" />
<label for="nav-trigger" class="navicon-button x">
<div class="navicon"></div>
</label>
<label for="nav-trigger" class="overlay"></label>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="RTMClient.html">RTMClient</a><ul class='methods'><li data-type='method'><a href="RTMClient.html#get">get</a></li><li data-type='method'><a href="RTMClient.html#~auth/getAuthToken">auth/getAuthToken</a></li><li data-type='method'><a href="RTMClient.html#~auth/getAuthUrl">auth/getAuthUrl</a></li><li data-type='method'><a href="RTMClient.html#~auth/verifyAuthToken">auth/verifyAuthToken</a></li><li data-type='method'><a href="RTMClient.html#~user/create">user/create</a></li><li data-type='method'><a href="RTMClient.html#~user/export">user/export</a></li><li data-type='method'><a href="RTMClient.html#~user/exportToString">user/exportToString</a></li><li data-type='method'><a href="RTMClient.html#~user/import">user/import</a></li><li data-type='method'><a href="RTMClient.html#~user/importFromString">user/importFromString</a></li></ul></li><li><a href="RTMError.html">RTMError</a><ul class='methods'><li data-type='method'><a href="RTMError.html#.networkError">networkError</a></li><li data-type='method'><a href="RTMError.html#.rateLimitError">rateLimitError</a></li><li data-type='method'><a href="RTMError.html#.referenceError">referenceError</a></li><li data-type='method'><a href="RTMError.html#.responseError">responseError</a></li><li data-type='method'><a href="RTMError.html#.serverError">serverError</a></li><li data-type='method'><a href="RTMError.html#toString">toString</a></li></ul></li><li><a href="RTMList.html">RTMList</a></li><li><a href="RTMResponse.html">RTMResponse</a><ul class='methods'><li data-type='method'><a href="RTMResponse.html#has">has</a></li><li data-type='method'><a href="RTMResponse.html#toString">toString</a></li></ul></li><li><a href="RTMSuccess.html">RTMSuccess</a><ul class='methods'><li data-type='method'><a href="RTMSuccess.html#toString">toString</a></li></ul></li><li><a href="RTMTask.html">RTMTask</a></li><li><a href="RTMUser.html">RTMUser</a><ul class='methods'><li data-type='method'><a href="RTMUser.html#clearTaskIndexCache">clearTaskIndexCache</a></li><li data-type='method'><a href="RTMUser.html#get">get</a></li><li data-type='method'><a href="RTMUser.html#verifyAuthToken">verifyAuthToken</a></li><li data-type='method'><a href="RTMUser.html#~lists/add">lists/add</a></li><li data-type='method'><a href="RTMUser.html#~lists/archive">lists/archive</a></li><li data-type='method'><a href="RTMUser.html#~lists/get">lists/get</a></li><li data-type='method'><a href="RTMUser.html#~lists/remove">lists/remove</a></li><li data-type='method'><a href="RTMUser.html#~lists/rename">lists/rename</a></li><li data-type='method'><a href="RTMUser.html#~tasks/add">tasks/add</a></li><li data-type='method'><a href="RTMUser.html#~tasks/addTags">tasks/addTags</a></li><li data-type='method'><a href="RTMUser.html#~tasks/complete">tasks/complete</a></li><li data-type='method'><a href="RTMUser.html#~tasks/decreasePriority">tasks/decreasePriority</a></li><li data-type='method'><a href="RTMUser.html#~tasks/get">tasks/get</a></li><li data-type='method'><a href="RTMUser.html#~tasks/getTask">tasks/getTask</a></li><li data-type='method'><a href="RTMUser.html#~tasks/increasePriority">tasks/increasePriority</a></li><li data-type='method'><a href="RTMUser.html#~tasks/move">tasks/move</a></li><li data-type='method'><a href="RTMUser.html#~tasks/postpone">tasks/postpone</a></li><li data-type='method'><a href="RTMUser.html#~tasks/priority">tasks/priority</a></li><li data-type='method'><a href="RTMUser.html#~tasks/remove">tasks/remove</a></li><li data-type='method'><a href="RTMUser.html#~tasks/removeTags">tasks/removeTags</a></li><li data-type='method'><a href="RTMUser.html#~tasks/setDueDate">tasks/setDueDate</a></li><li data-type='method'><a href="RTMUser.html#~tasks/setName">tasks/setName</a></li><li data-type='method'><a href="RTMUser.html#~tasks/setURL">tasks/setURL</a></li><li data-type='method'><a href="RTMUser.html#~tasks/uncomplete">tasks/uncomplete</a></li></ul></li></ul>
</nav>
<div id="main">
<h1 class="page-title">user/tasks.js</h1>
<section>
<article>
<pre class="prettyprint source linenums"><code>'use strict';
const _tasks = require('../task/helper.js');
const _lists = require('../list/helper.js');
const taskIds = require('../utils/taskIds.js');
const errors = require('../response/error.js');
/**
* This module returns the RTM Tasks-related functions for the RTMUser
* @param {RTMUser} user The RTM User instance
* @returns {{get: function, add:function, remove: function, complete: function, uncomplete: function, addTags: function, removeTags: function, priority: function, decreasePriority: function, increasePriority: function, move: function, setDueDate: function, postpone: function, setName: function}}
* @private
*/
module.exports = function(user) {
let rtn = {};
/**
* Get the list of RTM Tasks for this User.
* @param {string} [filter] Tasks Filter (RTM Advanced Search Syntax)
* @param {function} callback Callback function(err, tasks)
* @param {RTMError} callback.err RTM API Error Response, if encountered
* @param {RTMTask[]} callback.tasks List of User's RTM Tasks
* @function RTMUser~tasks/get
*/
rtn.get = function(filter, callback) {
if ( callback === undefined && typeof filter === 'function' ) {
callback = filter;
filter = "";
}
// Callback counters
let count = 0;
let calls = 2;
let returned = false;
// Lists and Tasks
let LISTS = {};
let TASKS = [];
// Update the User's Lists and Tasks
_lists.get(user, function(err, lists) {
if ( lists ) {
for ( let i = 0; i < lists.length; i++ ) {
LISTS[lists[i].id] = lists[i];
}
}
_tasksUpdateCallback(err);
});
_tasks.get(user, filter, function(err, tasks) {
TASKS = tasks;
_tasksUpdateCallback(err);
});
// Callback for each of list and task updates
function _tasksUpdateCallback(err) {
count++;
if ( !returned ) {
if ( err ) {
returned = true;
return callback(err);
}
else if ( count === calls ) {
returned = true;
_parseTasks();
return callback(null, TASKS);
}
}
}
// Add the List to each Task
function _parseTasks() {
for ( let i = 0; i < TASKS.length; i++ ) {
let list = LISTS[TASKS[i].list_id];
if ( list === undefined ) {
list = {
id: TASKS[i].list_id,
name: "List #" + TASKS[i].list_id
}
}
TASKS[i]._list = list;
}
}
};
/**
* Get the RTMTask specified by its index
* @param {int} index Task Index
* @param {function} callback Callback function(err, task)
* @param {RTMError} callback.err RTM API Error Response, if encountered
* @param {RTMTask} callback.task Matching RTM Task
* @function RTMUser~tasks/getTask
*/
rtn.getTask = function(index, callback) {
// Get Task Info
_getTaskInfo(index, function(err, listId, taskSeriesId, taskId) {
if ( err ) {
return callback(err);
}
// Get Task From API
user.tasks.get(function(err, tasks) {
if ( err ) {
return callback(err);
}
// Find Matching Task
let found = false;
for ( let i = 0; i < tasks.length; i++ ) {
if ( !found && tasks[i].task_id === taskId ) {
found = true;
return callback(null, tasks[i]);
}
}
// Task Not Found
if ( !found ) {
return callback(errors.referenceError());
}
});
});
};
/**
* Add a new RTM Task for this User
* @param {string} name Task Name (can include 'Smart Add' syntax)
* @param {object} [props] Task Properties
* @param {string} props.due Task Due Date (RTM supported date format)
* @param {int} props.priority Task Priority (1, 2, 3)
* @param {string} props.list Task List Name
* @param {string[]} props.tags Task Tags
* @param {string} props.location Task Location Name
* @param {string} props.start Task Start Date (RTM supported date format)
* @param {string} props.repeat Task Repeat Format (RTM supported repeat format)
* @param {string} props.estimate Task Time Estimate (RTM supported time estimate format)
* @param {string} props.to Contact Name to give Task to (existing contact or email address)
* @param {string} props.url Task Reference URL
* @param {string} props.note Task Note
* @param {function} callback Callback function(err)
* @param {RTMError} callback.err RTM API Error Response, if encountered
* @function RTMUser~tasks/add
*/
rtn.add = function(name, props, callback) {
if ( callback === undefined && typeof props === 'function' ) {
callback = props;
props = {};
}
return _tasks.add(name, props, user, callback);
};
/**
* Mark the specified Task as complete
* @param {int} index Task Index
* @param {function} callback Callback function(err)
* @param {RTMError} callback.err RTM API Error Response, if encountered
* @function RTMUser~tasks/complete
*/
rtn.complete = function(index, callback) {
// Get the Task
_getTaskInfo(index, function(err, listId, taskSeriesId, taskId) {
if ( err ) {
return callback(err);
}
// Complete the Task
return _tasks.complete(
listId,
taskSeriesId,
taskId,
user,
callback
);
});
};
/**
* Mark the specified Task as NOT complete
* @param {int} index Task Index
* @param {function} callback Callback function(err)
* @param {RTMError} callback.err RTM API Error Response, if encountered
* @function RTMUser~tasks/uncomplete
*/
rtn.uncomplete = function(index, callback) {
// Get the Task
_getTaskInfo(index, function(err, listId, taskSeriesId, taskId) {
if ( err ) {
return callback(err);
}
// Complete the Task
return _tasks.uncomplete(
listId,
taskSeriesId,
taskId,
user,
callback
);
});
};
/**
* Set the priority of the specified Task
* @param {int} index Task Index
* @param {int} priority Task Priority
* @param {function} callback Callback function(err)
* @param {RTMError} callback.err RTM API Error Response, if encountered
* @function RTMUser~tasks/priority
*/
rtn.priority = function(index, priority, callback) {
// Get the Task
_getTaskInfo(index, function(err, listId, taskSeriesId, taskId) {
if ( err ) {
return callback(err);
}
// Set the Priority
return _tasks.priority(
listId,
taskSeriesId,
taskId,
priority,
user,
callback
);
});
};
/**
* Add the specified tag(s) to the Task
* @param {int} index Task Index
* @param {string|string[]} tags Tag(s) to add to task
* @param {function} callback Callback function(err)
* @param {RTMError} callback.err RTM API Error Response, if encountered
* @function RTMUser~tasks/addTags
*/
rtn.addTags = function(index, tags, callback) {
// Make sure tags is an array
if ( !Array.isArray(tags) ) {
tags = [tags];
}
// Get the Task
_getTaskInfo(index, function(err, listId, taskSeriesId, taskId) {
if ( err ) {
return callback(err);
}
// Add the Tags
return _tasks.addTags(
listId,
taskSeriesId,
taskId,
tags,
user,
callback
);
});
};
/**
* Remove the specified Task from the User's Account
* @param {int} index Task Index
* @param {function} callback Callback function(err)
* @param {RTMError} callback.err RTM API Error Response, if encountered
* @function RTMUser~tasks/remove
*/
rtn.remove = function(index, callback) {
// Get the Task
_getTaskInfo(index, function(err, listId, taskSeriesId, taskId) {
if ( err ) {
return callback(err);
}
// Remove the Task
return _tasks.remove(
listId,
taskSeriesId,
taskId,
user,
callback
);
});
};
/**
* Increase the Priority of the specified Task
* @param {int} index Task Index
* @param {function} callback Callback function(err)
* @param {RTMError} callback.err RTM API Error Response, if encountered
* @function RTMUser~tasks/increasePriority
*/
rtn.increasePriority = function(index, callback) {
// Get the Task
_getTaskInfo(index, function(err, listId, taskSeriesId, taskId) {
if ( err ) {
return callback(err);
}
// Increase the Priority of the Task
return _tasks.movePriority(
listId,
taskSeriesId,
taskId,
'up',
user,
callback
);
});
};
/**
* Decrease the Priority of the specified Task
* @param {int} index Task Index
* @param {function} callback Callback function(err)
* @param {RTMError} callback.err RTM API Error Response, if encountered
* @function RTMUser~tasks/decreasePriority
*/
rtn.decreasePriority = function(index, callback) {
// Get the Task
_getTaskInfo(index, function(err, listId, taskSeriesId, taskId) {
if ( err ) {
return callback(err);
}
// Decrease the Priority of the Task
return _tasks.movePriority(
listId,
taskSeriesId,
taskId,
'down',
user,
callback
);
});
};
/**
* Move the specified Task to a different List
* @param {int} index Task Index
* @param {string} listName List Name to move Task to
* @param {function} callback Callback function(err)
* @param {RTMError} callback.err RTM API Error Response, if encountered
* @function RTMUser~tasks/move
*/
rtn.move = function(index, listName, callback) {
// Get the Task
_getTaskInfo(index, function(err, listId, taskSeriesId, taskId) {
if ( err ) {
return callback(err);
}
// Get the List
user.lists.get(function(err, lists) {
if ( err ) {
return callback(err);
}
// Find the List
let id = [];
for ( let i = 0; i < lists.length; i++ ) {
if ( lists[i].name.toLowerCase() === listName.toLowerCase() ) {
id.push(lists[i].id);
}
}
// No List Match
if ( id.length !== 1 ) {
return callback(errors.referenceError());
}
// Move the Task
else {
return _tasks.move(
listId,
taskSeriesId,
taskId,
id[0],
user,
callback
);
}
});
});
};
/**
* Postpone the due date of the Task by 1 day
* @param {int} index Task Index
* @param {function} callback Callback function(err)
* @param {RTMError} callback.err RTM API Error Response, if encountered
* @function RTMUser~tasks/postpone
*/
rtn.postpone = function(index, callback) {
// Get the Task
_getTaskInfo(index, function(err, listId, taskSeriesId, taskId) {
if ( err ) {
return callback(err);
}
// Postpone the Task
return _tasks.postpone(
listId,
taskSeriesId,
taskId,
user,
callback
);
});
};
/**
* Remove the specified tag(s) from the Task
* @param {int} index Task Index
* @param {string|string[]} tags Tags to remove from the Task
* @param {function} callback Callback function(err)
* @param {RTMError} callback.err RTM API Error Response, if encountered
* @function RTMUser~tasks/removeTags
*/
rtn.removeTags = function(index, tags, callback) {
// Make sure tags is an array
if ( !Array.isArray(tags) ) {
tags = [tags];
}
// Get the Task
_getTaskInfo(index, function(err, listId, taskSeriesId, taskId) {
if ( err ) {
return callback(err);
}
// Remove the Tags
return _tasks.removeTags(
listId,
taskSeriesId,
taskId,
tags,
user,
callback
);
});
};
/**
* Set the Due Date of the specified Task
* @param {int} index Task Index
* @param {string} due The Due Date of the Task (RTM parsed date)
* @param {function} callback Callback function(err)
* @param {RTMError} callback.err RTM API Error Response, if encountered
* @function RTMUser~tasks/setDueDate
*/
rtn.setDueDate = function(index, due, callback) {
// Get the Task
_getTaskInfo(index, function(err, listId, taskSeriesId, taskId) {
if ( err ) {
return callback(err);
}
// Decrease the Priority of the Task
return _tasks.setDueDate(
listId,
taskSeriesId,
taskId,
due,
user,
callback
);
});
};
/**
* Set the Name of the specified Task
* @param {int} index Task Index
* @param {string} name New Task Name
* @param {function} callback Callback function(err)
* @param {RTMError} callback.err RTM API Error Response, if encountered
* @function RTMUser~tasks/setName
*/
rtn.setName = function(index, name, callback) {
// Get the Task
_getTaskInfo(index, function(err, listId, taskSeriesId, taskId) {
if ( err ) {
return callback(err);
}
// Decrease the Priority of the Task
return _tasks.setName(
listId,
taskSeriesId,
taskId,
name,
user,
callback
);
});
};
/**
* Set the URL of the specified Task
* @param {int} index Task Index
* @param {string} url New Task URL
* @param {function} callback Callback function(err)
* @param {RTMError} callback.err RTM API Error Response, if encountered
* @function RTMUser~tasks/setURL
*/
rtn.setURL = function(index, url, callback) {
// Get the Task
_getTaskInfo(index, function(err, listId, taskSeriesId, taskId) {
if ( err ) {
return callback(err);
}
// Decrease the Priority of the Task
return _tasks.setURL(
listId,
taskSeriesId,
taskId,
url,
user,
callback
);
});
};
/**
* Get the Matching Task IDs by Index
* @param {int} index Task Index
* @param callback Callback function(err, list_id, taskseries_id, task_id)
* @private
*/
function _getTaskInfo(index, callback) {
// Get IDs
let listId = taskIds.getListId(user.id, index);
let taskSeriesId = taskIds.getTaskSeriesId(user.id, index);
let taskId = taskIds.getTaskId(user.id, index);
// All IDs found...
if ( listId !== undefined && taskSeriesId !== undefined && taskId !== undefined ) {
return callback(null, listId, taskSeriesId, taskId);
}
// Get Task From API
user.tasks.get(function(err, tasks) {
if ( err ) {
return callback(err);
}
// Find Matching Task
let found = false;
for ( let i = 0; i < tasks.length; i++ ) {
if ( !found && tasks[i].task_id === taskId ) {
found = true;
return callback(null, tasks[i].list_id, tasks[i].taskseries_id, tasks[i].task_id);
}
}
// Task Not Found
if ( !found ) {
return callback(errors.referenceError());
}
});
}
return rtn;
};</code></pre>
</article>
</section>
</div>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Wed Jan 09 2019 17:57:03 GMT-0500 (EST) using the <a href="https://github.com/dwaring87/docdash">/docdash</a> theme.
</footer>
<script>prettyPrint();</script>
<script src="scripts/linenumber.js"></script>
</body>
</html>