client/index.js

  1. 'use strict';
  4. /**
  5.  * ### RTM API Client
  6.  *
  7.  * This Class is used to represent an RTM API Client.  The Client contains
  8.  * the API Key, API Secret and access permissions used to access the
  9.  * RTM API endpoints.
  10.  *
  11.  * It also includes API wrapper functions for making a general RTM API request
  12.  * as well as the auth-related functions.
  13.  *
  14.  * #### Usage
  15.  *
  16.  * The `RTMClient` Class is what is exported when the entire `rtm-api` module
  17.  * is loaded via `require`.
  18.  *
  19.  * ```
  20.  * const RTM = require('rtm-api');
  21.  * let client = new RTM(API_KEY, API_SECRET, RTM.PERM_DELETE);
  22.  * ```
  23.  *
  24.  * #### Auth Example
  25.  *
  26.  * This example gets an Auth URL to be opened by the RTM User
  27.  *
  28.  * ```
  29.  * client.auth.getAuthUrl(function(err, authUrl, frob) {
  30.  *    // Have user authenticate and authorize the program with the authUrl
  31.  *    // Once authorized by the user, use the frob to get an authToken
  32.  * )};
  33.  * ```
  34.  *
  35.  * #### RTM API Example
  36.  *
  37.  * This example makes an RTM API request using the method `rtm.method` and the
  38.  * parameter foo=bar.
  39.  *
  40.  * ```
  41.  * client.get('rtm.method', {foo: "bar"}, function(err, resp) {
  42.  *    if ( err ) {
  43.  *      // handle error
  44.  *    }
  45.  *    // use the response
  46.  * });
  47.  * ```
  48.  *
  49.  * See {@link RTMUser#get|RTMUser.get} for making User-authenticated API requests.
  50.  *
  51.  * @class
  52.  */
  53. class RTMClient {
  55.   /**
  56.    * Create a new RTM Client with the specified API access information
  57.    * @param {string} key RTM API Client Key
  58.    * @param {string} secret RTM API Client Secret
  59.    * @param {string} [perms=RTMClient.PERM_READ] RTM API Client Access Permissions. This
  60.    * should be one of {@link RTMClient.PERM_READ}, {@link RTMClient.PERM_WRITE} or
  61.    * {@link RTMClient.PERM_DELETE}.
  62.    * @constructor
  63.    */
  64.   constructor(key, secret, perms=RTMClient.PERM_READ) {
  65.     this._apiKey = key;
  66.     this._apiSecret = secret;
  67.     this._perms = perms;
  68.   }
  71.   /**
  72.    * RTM API Client Key
  73.    * @type {string}
  74.    */
  75.   get key() {
  76.     return this._apiKey;
  77.   }
  79.   /**
  80.    * RTM API Client Secret
  81.    * @type {string}
  82.    */
  83.   get secret() {
  84.     return this._apiSecret;
  85.   }
  87.   /**
  88.    * RTM API Client Access Permissions
  89.    * @type {string}
  90.    */
  91.   get perms() {
  92.     return this._perms;
  93.   }
  97.   // ===== USER FUNCTIONS ===== //
  99.   /**
  100.    * User export/import-related functions:
  101.    * - {@link RTMClient~user/create|create}
  102.    * - {@link RTMClient~user/export|export}
  103.    * - {@link RTMClient~user/exportToString|exportToString}
  104.    * - {@link RTMClient~user/import|import}
  105.    * - {@link RTMClient~user/importFromString|importFromString}
  106.    * @returns {{create: function, export: function, exportToString: function, import: function, importFromString: function}}
  107.    */
  108.   get user() {
  109.     return require('./user.js')(this);
  110.   }
  114.   // ===== API HELPER FUNCTIONS ===== //
  117.   /**
  118.    * Make the specified RTM API call.
  119.    *
  120.    * The `method` should be the name of the RTM API method.  Any necessary
  121.    * parameters should be provided with `params` as an object with the properties
  122.    * of the object as the parameters' key/value pairs.
  123.    *
  124.    * RTM API methods that require an AuthToken should set the `params` `auth_token`
  125.    * property or provide a valid `RTMUser` with an AuthToken.
  126.    * @param {string} method RTM API Method
  127.    * @param {object} [params] RTM Method Parameters (as an object with key/value pairs)
  128.    * @param {RTMUser} [user=undefined] The RTM User making the request
  129.    * @param {function} callback Callback function(err, resp)
  130.    * @param {RTMError} callback.err RTM Error Response, if encountered
  131.    * @param {RTMSuccess} callback.resp The parsed RTM API Response, if successful
  132.    */
  133.   get(method, params, user, callback) {
  134.     require('../utils/get.js')(method, params, user, this, callback);
  135.   }
  137.   /**
  138.    * Auth-related functions:
  139.    * - {@link RTMClient~auth/getAuthUrl|getAuthUrl}
  140.    * - {@link RTMClient~auth/getAuthToken|getAuthToken}
  141.    * - {@link RTMClient~auth/verifyAuthToken|verifyAuthToken}
  142.    * @returns {{getAuthUrl: function, getAuthToken: function, verifyAuthToken: function}}
  143.    */
  144.   get auth() {
  145.     return require('./auth.js')(this);
  146.   }
  148. }
  152. // ==== RTM API PERMISSION LEVELS ==== //
  154. /**
  155.  * RTM API Access: `read` -
  156.  * gives the ability to read task, contact, group and list details and contents.
  157.  * @type {string}
  158.  * @default
  159.  */
  160. RTMClient.PERM_READ = 'read';
  162. /**
  163.  * RTM API Access: `write` -
  164.  * gives the ability to add and modify task, contact, group and list details and
  165.  * contents (also allows you to `read`).
  166.  * @type {string}
  167.  * @default
  168.  */
  169. RTMClient.PERM_WRITE = 'write';
  171. /**
  172.  * RTM API Access: `delete` -
  173.  * gives the ability to delete task, contacts, groups and list (also allows
  174.  * you to `read` and `write`).
  175.  * @type {string}
  176.  * @default
  177.  */
  178. RTMClient.PERM_DELETE = 'delete';
  182. module.exports = RTMClient;