rtm-api
Version:
Remember the Milk API Interface
347 lines (292 loc) • 13 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>user/index.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/index.js</h1>
<section>
<article>
<pre class="prettyprint source linenums"><code>'use strict';
const config = require('../../rtm.json');
/**
* ### RTM User
*
* This Class is used to represent an authorized RTM User. An `RTMUser` instance
* contains the user's ID, username and fullname as well as an auth token that can
* be used to make user-authenticated API requests.
*
* #### Usage
*
* An `RTMUser` instance can created manually with an {@link RTMClient}:
*
* ```
* let user = client.user.create(1234, 'username', 'full name', 'auth_token');
* ```
*
* or can be returned through the RTM API auth process (specifically the callback
* function from {@link RTMClient~auth/getAuthToken|RTMClient.auth.getAuthToken()}).
*
* ```
* // Get an Auth URL
* client.auth.getAuthUrl(function(err, authUrl, frob) {
*
* // Have the User open this URL in their browser
* console.log(authUrl);
*
* // Get an authenticated RTMUser
* client.auth.getAuthToken(frob, function(err, user) {
*
* // user is an instance of RTMUser
*
* });
*
* });
* ```
*
* #### API Wrappers
*
* The `RTMUser` also includes a number of wrapper functions for commonly
* used RTM API methods dealing with Lists and Tasks.
*
* **Tasks:**
*
* For example, to get the User's RTM Tasks:
*
* ```
* user.tasks.get(function(err, tasks) {
* console.log(tasks);
* });
* ```
*
* The `tasks.get()` function will also fetch the User's RTM Lists and add
* the List (as an `RTMList` instance) that contains the Task to the `list`
* property of the `RTMTask`.
*
* @class
*/
class RTMUser {
/**
* Create a new RTM User.
*
* An `RTMUser` can be used to make user-authenticated RTM API calls and also
* includes wrapper methods around some common RTM API methods.
* @param {number} id The RTM User's ID
* @param {string} username The RTM User's username
* @param {string} fullname The RTM User's full name
* @param {string} authToken The RTM User's Auth Token
* @constructor
*/
constructor(id, username, fullname, authToken) {
this._id = parseFloat(id);
this._username = username;
this._fullname = fullname;
this._authToken = authToken;
this._client = undefined;
this._timeline = undefined;
this._burstsRemaining = config.api.rate.bursts;
this._lastBurst = undefined;
this._nextRequest = new Date().getTime();
}
// ==== RTMUser PROPERTY GETTERS & SETTERS ==== //
/**
* RTM User ID
* @type {number}
*/
get id() {
return this._id;
}
/**
* RTM User Username
* @type {string}
*/
get username() {
return this._username;
}
/**
* RTM User fullname
* @type {string}
*/
get fullname() {
return this._fullname;
}
/**
* RTM User Auth Token
* @type {string}
*/
get authToken() {
return this._authToken;
}
/**
* Set the RTM User Auth Token
* @param {string} token
* @private
*/
set authToken(token) {
this._authToken = token;
}
/**
* The {@link RTMClient} that authorized this User
* @type {RTMClient}
*/
get client() {
if ( !this._client ) {
throw "User does not have Client specified";
}
return this._client;
}
/**
* Set the Client that authorized this User
* @param {RTMClient} client
* @private
*/
set client(client) {
this._client = client;
}
/**
* The RTM Timeline for this User
* @type {number}
*/
get timeline() {
if ( !this._timeline ) {
throw "User does not have a valid timeline set";
}
return this._timeline;
}
/**
* Set the RTM Timeline for this User
* @param {number} timeline
* @private
*/
set timeline(timeline) {
this._timeline = parseFloat(timeline);
}
// ==== REQUEST RATE FUNCTIONS ==== //
/**
* Time (ms) to wait to make an API Request
* @returns {number}
*/
get requestTimeout() {
let now = new Date().getTime();
let next = this._nextRequest;
let wait = next - now < 0 ? 0 : next - now;
// Default Timeout
let timeout = config.api.rate.timeout;
// Can we start bursting again?
if ( this._lastBurst !== undefined ) {
let burstDelta = now - this._lastBurst;
if ( burstDelta > config.api.rate.burstWait ) {
this._burstsRemaining = config.api.rate.bursts;
}
}
// Do we have bursts remaining?
if ( this._burstsRemaining > 0 ) {
this._burstsRemaining--;
timeout = config.api.rate.burstTimeout;
if ( this._burstsRemaining === 0 ) {
this._lastBurst = now;
}
}
// Set Next Request Time
this._nextRequest = now + wait + timeout;
// Return wait time
return wait;
}
// ==== API HELPER FUNCTIONS ==== //
/**
* Make the specified RTM API call.
*
* The `method` should be the name of the RTM API method. Any necessary
* parameters should be provided with `params` as an object with the properties
* of the object as the parameters' key/value pairs.
*
* This function will automatically add the User's auth token to the request.
* @param {string} method RTM API Method
* @param {object} [params] RTM API Method Parameters
* @param {function} callback Callback function(err, resp)
* @param {RTMError} callback.err RTM Error Response, if encountered
* @param {RTMSuccess} callback.resp The parsed RTM API Response, if successful
*/
get(method, params, callback) {
require('../utils/get.js')(method, params, this, this.client, callback);
}
/**
* Verify the Auth Token of this RTM User
* @param {function} callback Callback function(err, verified)
* @param {RTMError} callback.err RTM Error, if encountered (excluding a `Login failed / Invalid auth token` error)
* @param {boolean} callback.verified `true` if the User's auth token was successfully verified or `false` if
* a `Login failed / Invalid auth token` error was encountered
*/
verifyAuthToken(callback) {
require('../utils/auth.js').verifyAuthToken(this.authToken, this.client, callback);
}
/**
* Clear the Task Index Cache for this RTM User
*/
clearTaskIndexCache() {
require('../utils/taskIds.js').clear(this.id);
}
/**
* RTM List related functions:
* - {@link RTMUser~lists/get|get}
* - {@link RTMUser~lists/add|add}
* - {@link RTMUser~lists/rename|rename}
* - {@link RTMUser~lists/remove|remove}
* @returns {{get: function, add: function, remove: function, rename: function}}
*/
get lists() {
return require('./lists.js')(this);
}
/**
* RTM Task related functions:
* - {@link RTMUser~tasks/get|get}
* - {@link RTMUser~tasks/add|add}
* - {@link RTMUser~tasks/remove|remove}
* - {@link RTMUser~tasks/complete|complete}
* - {@link RTMUser~tasks/uncomplete|uncomplete}
* - {@link RTMUser~tasks/addTags|addTags}
* - {@link RTMUser~tasks/removeTags|removeTags}
* - {@link RTMUser~tasks/priority|priority}
* - {@link RTMUser~tasks/decreasePriority|decreasePriority}
* - {@link RTMUser~tasks/increasePriority|increasePriority}
* - {@link RTMUser~tasks/move|move}
* - {@link RTMUser~tasks/setDueDate|setDueDate}
* - {@link RTMUser~tasks/postpone|postpone}
* - {@link RTMUser~tasks/setName|setName}
* @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}}
*/
get tasks() {
return require('./tasks.js')(this);
}
}
module.exports = RTMUser;
</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">@dwaring87/docdash</a> theme.
</footer>
<script>prettyPrint();</script>
<script src="scripts/linenumber.js"></script>
</body>
</html>