@beauraines/rtm-api 1.4.1

package/jsdoc.json

@@ -0,0 +1,13 @@
+{
+    "plugins": ["plugins/markdown"],
+    "source": {
+        "include": ["src/"],
+        "exclude": ["node_modules/"],
+        "includePattern": ".+\\.js(doc|x)?$",
+        "excludePattern": "(^|\\/|\\\\)_"
+    },
+    "opts": {
+        "destination": "docs/",
+        "recurse": true
+    }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@beauraines/rtm-api",
+  "version": "1.4.1",
+  "description": "Remember the Milk API Interface",
+  "author": "Beau Raines <beau.raines@gmail.com>",
+  "license": "MIT",
+  "keywords": [
+    "rtm",
+    "api",
+    "remember the milk",
+    "tasks",
+    "todo",
+    "gtd"
+  ],
+  "main": "src/client/index.js",
+  "scripts": {
+    "docs": "jsdoc -c jsdoc.json --readme README.md --template $NODE_PATH/@dwaring87/docdash"
+  },
+  "devDependencies": {
+    "@dwaring87/docdash": "^0.4.1",
+    "jsdoc": "^3.6.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/beauraines/rtm-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/beauraines/rtm-api/issues"
+  },
+  "dependencies": {
+    "node-fetch": "^2.6.7"
+  }
+}

package/src/client/auth.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const _auth = require('../utils/auth.js');
+
+
+/**
+ * This module returns the auth-related functions for RTMClient
+ * @param {RTMClient} client RTMClient instance
+ * @returns {{getAuthUrl: function, getAuthToken: function, verifyAuthToken: function}}
+ * @private
+ */
+module.exports = function(client) {
+  let rtn = {};
+
+  /**
+   * Get an Auth URL.
+   *
+   * This function will generate an Auth URL that will be given to the RTM User
+   * to authorize the RTM Client to access their account.  It will also request
+   * a frob that will be used to gain an auth token in `getAuthToken()`.
+   * @param {function} callback Callback function(err, authUrl, frob)
+   * @param {RTMError} callback.err RTM Error Response, if encountered
+   * @param {string} callback.authUrl Auth URL to be given to User
+   * @param {string} callback.frob Auth Frob to be used in `getAuthToken()`
+   * @function RTMClient~auth/getAuthUrl
+   */
+  rtn.getAuthUrl = function(callback) {
+    _auth.getAuthUrl(client, callback);
+  };
+
+  /**
+   * Get an Auth Token.
+   *
+   * This function takes the frob that was generated by `getAuthUrl()` and
+   * requests an Auth Token.  The callback function will return an `RTMUser`
+   * which will include the RTM User's information and an Auth Token to be
+   * used in future API calls.
+   * @param {string} frob Auth Frob from `getAuthUrl()`
+   * @param {function} callback Callback function(err, user)
+   * @param {RTMError} callback.err RTM Error Response, if encountered
+   * @param {RTMUser} callback.user RTM User, with user information and auth token
+   * @function RTMClient~auth/getAuthToken
+   */
+  rtn.getAuthToken = function(frob, callback) {
+    _auth.getAuthToken(frob, client, callback);
+  };
+
+  /**
+   * Verify Auth Token.
+   *
+   * This function will check if the User's Auth Token is still valid and
+   * can be used to make authenticated RTM API requests.
+   * @param {string|RTMUser} token Auth Token or RTMUser containing an auth token
+   * @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
+   * @function RTMClient~auth/verifyAuthToken
+   */
+  rtn.verifyAuthToken = function(token, callback) {
+    _auth.verifyAuthToken(token, client, callback);
+  };
+
+  return rtn;
+};

package/src/client/index.js

@@ -0,0 +1,182 @@
+'use strict';
+
+
+/**
+ * ### RTM API Client
+ *
+ * This Class is used to represent an RTM API Client.  The Client contains
+ * the API Key, API Secret and access permissions used to access the
+ * RTM API endpoints.
+ *
+ * It also includes API wrapper functions for making a general RTM API request
+ * as well as the auth-related functions.
+ *
+ * #### Usage
+ *
+ * The `RTMClient` Class is what is exported when the entire `rtm-api` module
+ * is loaded via `require`.
+ *
+ * ```
+ * const RTM = require('rtm-api');
+ * let client = new RTM(API_KEY, API_SECRET, RTM.PERM_DELETE);
+ * ```
+ *
+ * #### Auth Example
+ *
+ * This example gets an Auth URL to be opened by the RTM User
+ *
+ * ```
+ * client.auth.getAuthUrl(function(err, authUrl, frob) {
+ *    // Have user authenticate and authorize the program with the authUrl
+ *    // Once authorized by the user, use the frob to get an authToken
+ * )};
+ * ```
+ *
+ * #### RTM API Example
+ *
+ * This example makes an RTM API request using the method `rtm.method` and the
+ * parameter foo=bar.
+ *
+ * ```
+ * client.get('rtm.method', {foo: "bar"}, function(err, resp) {
+ *    if ( err ) {
+ *      // handle error
+ *    }
+ *    // use the response
+ * });
+ * ```
+ *
+ * See {@link RTMUser#get|RTMUser.get} for making User-authenticated API requests.
+ *
+ * @class
+ */
+class RTMClient {
+
+  /**
+   * Create a new RTM Client with the specified API access information
+   * @param {string} key RTM API Client Key
+   * @param {string} secret RTM API Client Secret
+   * @param {string} [perms=RTMClient.PERM_READ] RTM API Client Access Permissions. This
+   * should be one of {@link RTMClient.PERM_READ}, {@link RTMClient.PERM_WRITE} or
+   * {@link RTMClient.PERM_DELETE}.
+   * @constructor
+   */
+  constructor(key, secret, perms=RTMClient.PERM_READ) {
+    this._apiKey = key;
+    this._apiSecret = secret;
+    this._perms = perms;
+  }
+
+
+  /**
+   * RTM API Client Key
+   * @type {string}
+   */
+  get key() {
+    return this._apiKey;
+  }
+
+  /**
+   * RTM API Client Secret
+   * @type {string}
+   */
+  get secret() {
+    return this._apiSecret;
+  }
+
+  /**
+   * RTM API Client Access Permissions
+   * @type {string}
+   */
+  get perms() {
+    return this._perms;
+  }
+
+
+
+  // ===== USER FUNCTIONS ===== //
+
+  /**
+   * User export/import-related functions:
+   * - {@link RTMClient~user/create|create}
+   * - {@link RTMClient~user/export|export}
+   * - {@link RTMClient~user/exportToString|exportToString}
+   * - {@link RTMClient~user/import|import}
+   * - {@link RTMClient~user/importFromString|importFromString}
+   * @returns {{create: function, export: function, exportToString: function, import: function, importFromString: function}}
+   */
+  get user() {
+    return require('./user.js')(this);
+  }
+
+
+
+  // ===== 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.
+   *
+   * RTM API methods that require an AuthToken should set the `params` `auth_token`
+   * property or provide a valid `RTMUser` with an AuthToken.
+   * @param {string} method RTM API Method
+   * @param {object} [params] RTM Method Parameters (as an object with key/value pairs)
+   * @param {RTMUser} [user=undefined] The RTM User making the request
+   * @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, user, callback) {
+    require('../utils/get.js')(method, params, user, this, callback);
+  }
+
+  /**
+   * Auth-related functions:
+   * - {@link RTMClient~auth/getAuthUrl|getAuthUrl}
+   * - {@link RTMClient~auth/getAuthToken|getAuthToken}
+   * - {@link RTMClient~auth/verifyAuthToken|verifyAuthToken}
+   * @returns {{getAuthUrl: function, getAuthToken: function, verifyAuthToken: function}}
+   */
+  get auth() {
+    return require('./auth.js')(this);
+  }
+
+}
+
+
+
+// ==== RTM API PERMISSION LEVELS ==== //
+
+/**
+ * RTM API Access: `read` -
+ * gives the ability to read task, contact, group and list details and contents.
+ * @type {string}
+ * @default
+ */
+RTMClient.PERM_READ = 'read';
+
+/**
+ * RTM API Access: `write` -
+ * gives the ability to add and modify task, contact, group and list details and
+ * contents (also allows you to `read`).
+ * @type {string}
+ * @default
+ */
+RTMClient.PERM_WRITE = 'write';
+
+/**
+ * RTM API Access: `delete` -
+ * gives the ability to delete task, contacts, groups and list (also allows
+ * you to `read` and `write`).
+ * @type {string}
+ * @default
+ */
+RTMClient.PERM_DELETE = 'delete';
+
+
+
+module.exports = RTMClient;

package/src/client/user.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const RTMClient = require('./index.js');
+const RTMUser = require('../user/index.js');
+
+
+/**
+ * This module returns the user-related functions for RTMClient
+ * @param {RTMClient} client RTMClient instance
+ * @returns {{create: function, export: function, exportToString: function, import: function, importFromString: function}}
+ */
+module.exports = function(client) {
+  let rtn = {};
+
+  /**
+   * Create a new `RTMUser` manually.
+   *
+   * This will also set the User's RTM API Client to this `RTMClient`.
+   * @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
+   * @returns {RTMUser}
+   * @function RTMClient~user/create
+   */
+  rtn.create = function(id, username, fullname, authToken) {
+    let user = new RTMUser(id, username, fullname, authToken);
+    user.client = client;
+    return user;
+  };
+
+  /**
+   * Get the User's required information:
+   * - id
+   * - username
+   * - fullname
+   * - authToken
+   * - client (if set or use this `RTMClient`)
+   * @param {RTMUser} user The RTMUser to export
+   * @returns {object}
+   * @function RTMClient~user/export
+   */
+  rtn.export = function(user) {
+    let rtn = {
+      id: user.id,
+      username: user.username,
+      fullname: user.fullname,
+      authToken: user.authToken,
+      timeline: user._timeline
+    };
+    if ( user.client ) {
+      rtn.client = {
+        apiKey: user.client.key,
+        apiSecret: user.client.secret,
+        perms: user.client.perms
+      }
+    }
+    else {
+      rtn.client = {
+        apiKey: client.key,
+        apiSecret: client.key,
+        perms: client.perms
+      }
+    }
+
+    return rtn;
+  };
+
+  /**
+   * Get the User's required information as a JSON-string
+   * @param {RTMUser} user The RTMUser to export
+   * @returns {string}
+   * @function RTMClient~user/exportToString
+   */
+  rtn.exportToString = function(user) {
+    return JSON.stringify(rtn.export(user));
+  };
+
+  /**
+   * Create a new `RTMUser` from an exported User's properties
+   * @param {Object} properties The RTM User's required properties
+   * @returns {RTMUser}
+   * @function RTMClient~user/import
+   */
+  rtn.import = function(properties) {
+    if ( properties.id && properties.username && properties.fullname && properties.authToken ) {
+      let user = new RTMUser(properties.id, properties.username, properties.fullname, properties.authToken);
+      if ( properties.timeline ) {
+        user.timeline = properties.timeline;
+      }
+      if ( properties.client ) {
+        user.client = new RTMClient(properties.client.apiKey, properties.client.apiSecret, properties.client.perms);
+      }
+      return user;
+    }
+    else {
+      throw "Missing User Properties";
+    }
+  };
+
+  /**
+   * Create a new `RTMUser` from an exported User's properties' JSON-string
+   * @param {string} string JSON-string of RTM User's required properties
+   * @returns {RTMUser}
+   * @function RTMClient~user/importFromString
+   */
+  rtn.importFromString = function(string) {
+    return rtn.import(JSON.parse(string));
+  };
+
+  return rtn;
+};

package/src/list/helper.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const RTMList = require('./index.js');
+
+
+/**
+ * API Call: rtm.lists.getList
+ * @param user RTMUser
+ * @param callback Callback function(err, lists)
+ * @private
+ */
+function get(user, callback) {
+  user.get('rtm.lists.getList', function(err, resp) {
+    if ( err ) {
+      return callback(err);
+    }
+
+    // List of lists to return
+    let rtn = [];
+
+    // Parse each of the lists
+    let lists = resp.lists.list;
+    for ( let i = 0; i < lists.length; i++ ) {
+      rtn.push(
+        new RTMList(lists[i])
+      );
+    }
+
+    // Call the callback
+    return callback(null, rtn);
+  });
+}
+
+
+/**
+ * API Call: rtm.lists.add
+ * @param name RTM List Name
+ * @param [filter] RTM Smart List Filter
+ * @param user RTMUser
+ * @param callback Callback function(err)
+ * @private
+ */
+function add(name, filter, user, callback) {
+
+  // Parse Parameters
+  if ( callback === undefined && typeof user === 'function' ) {
+    callback = user;
+    user = filter;
+    filter = undefined;
+  }
+
+  // Invalid List Names
+  if ( name === 'Inbox' || name === 'Sent' ) {
+    throw "Invalid List Name"
+  }
+
+  // Set Parameters
+  let params = {
+    name: name,
+    timeline: user.timeline
+  };
+  if ( filter !== undefined ) {
+    params.filter = filter;
+  }
+
+  // Add List
+  user.get('rtm.lists.add', params, function(err) {
+    return callback(err);
+  });
+}
+
+/**
+ * API Call: rtm.lists.delete
+ * @param id RTM List ID
+ * @param user RTMUser
+ * @param callback Callback function(err)
+ * @private
+ */
+function remove(id, user, callback) {
+  let params = {
+    timeline: user.timeline,
+    list_id: id
+  };
+  user.get('rtm.lists.delete', params,  function(err) {
+    return callback(err);
+  });
+}
+
+/**
+ * API Call: rtm.lists.setName
+ * @param id RTM List ID
+ * @param name New RTM List Name
+ * @param user RTMUser
+ * @param callback Callback function(err)
+ * @private
+ */
+function rename(id, name, user, callback) {
+  let params = {
+    timeline: user.timeline,
+    list_id: id,
+    name: name
+  };
+  user.get('rtm.lists.setName', params, function(err) {
+    return callback(err);
+  });
+}
+
+/**
+ * API Call: rtm.lists.archive
+ * @param id RTM List ID
+ * @param user RTMUser
+ * @param callback Callback function(err)
+ * @private
+ */
+function archive(id, user, callback) {
+  let params = {
+    timeline: user.timeline,
+    list_id: id
+  };
+  user.get('rtm.lists.archive', params,  function(err) {
+    return callback(err);
+  });
+}
+
+module.exports = {
+  get: get,
+  add: add,
+  remove: remove,
+  rename: rename,
+  archive: archive
+};

package/src/list/index.js

@@ -0,0 +1,101 @@
+'use strict';
+
+
+/**
+ * ### RTM List
+ *
+ * This Class is used to represent the properties of an RTM List.
+ *
+ * All of the list properties from RTM are directly accessible from this Class.
+ *
+ * ```
+ * let list = new RTMList(...);
+ * let name = list.name;
+ * ```
+ * @class
+ */
+class RTMList {
+
+  /**
+   * Create a new RTM List
+   * @param {object} props The properties from the RTM API response `resp.lists.list`
+   */
+  constructor(props) {
+
+    /**
+     * List ID
+     * @type {Number}
+     */
+    this.id = parseFloat(props.id);
+
+    /**
+     * List Name
+     * @type {string}
+     */
+    this.name = props.name;
+
+    /**
+     * List Deleted Flag
+     * @type {boolean}
+     */
+    this.deleted = props.deleted.toString() === '1';
+
+    /**
+     * List Locked Flag
+     * @type {boolean}
+     */
+    this.locked = props.locked.toString() === '1';
+
+    /**
+     * List Archived Flag
+     * @type {boolean}
+     */
+    this.archived = props.archived.toString() === '1';
+
+    /**
+     * List Position
+     * @type {Number}
+     */
+    this.position = parseInt(props.position);
+
+    /**
+     * Smart List Flag
+     * @type {boolean}
+     */
+    this.smart = props.smart.toString() === '1';
+    if ( this.smart ) {
+
+      /**
+       * Smart List Filter
+       * @type {string}
+       */
+      this.filter = props.filter;
+
+    }
+
+    /**
+     * List Sort Order
+     * @type {Number}
+     */
+    this.sort_order = parseInt(props.sort_order);
+
+  }
+
+  /**
+   * All of the RTM List properties
+   * @type {object}
+   */
+  get props() {
+    let rtn = {};
+    for ( let key in this ) {
+      if ( this.hasOwnProperty(key) && key !== '_index' ) {
+        rtn[key] = this[key];
+      }
+    }
+    return rtn;
+  }
+
+}
+
+
+module.exports = RTMList;