@beauraines/rtm-api 1.4.1

package/src/response/error.js

@@ -0,0 +1,114 @@
+'use strict';
+
+const RTMResponse = require('./response.js');
+
+
+/**
+ * ### RTM Error Response
+ *
+ * This Class represents a failed request to the RTM API Server: the
+ * RTM API Server returned a response with a status of 'fail'.  This
+ * Class will include the error code and error message from the
+ * response.
+ *
+ * `RTMError` extends {@link RTMResponse}
+ * @class
+ * @alias RTMError
+ */
+class RTMError extends RTMResponse{
+
+  /**
+   * Create a new RTM Error Response
+   * @param {number} code Error Code
+   * @param {string} msg Error Message
+   * @constructor
+   */
+  constructor(code, msg) {
+    super(RTMResponse.STATUS_FAIL);
+    this._code = parseInt(code);
+    this._msg = msg;
+  }
+
+  /**
+   * The RTM Error Code
+   * @type {number}
+   */
+  get code() {
+    return this._code;
+  }
+
+  /**
+   * The RTM Error Message
+   * @type {string}
+   */
+  get msg() {
+    return this._msg;
+  }
+
+  /**
+   * Get a String representation of the Error
+   * @returns {string}
+   */
+  toString() {
+    return super.toString() + " ERROR " + this._code + ": " + this._msg;
+  }
+
+}
+
+
+// === CUSTOM ERRORS ==== //
+
+/**
+ * Create a new `RTMError` that represents a network error.
+ *
+ * Error Code: `-1`
+ * @returns {RTMError}
+ */
+RTMError.networkError = function() {
+  return new RTMError(-1, "Network Error: Could not make request to RTM API Server");
+};
+
+/**
+ * Create a new `RTMError` that represents an API response error.
+ *
+ * Error Code: `-2`
+ * @returns {RTMError}
+ */
+RTMError.responseError = function() {
+  return new RTMError(-2, "Response Error: Could not parse the response from the RTM API Server");
+};
+
+/**
+ * Create a new `RTMError` that represents an index error (ie, task index is out
+ * of range).
+ *
+ * Error Code: `-3`
+ * @returns {RTMError}
+ */
+RTMError.referenceError = function() {
+  return new RTMError(-3, "Reference Error: Could not find item by reference index number or name");
+};
+
+/**
+ * Create a new `RTMError` that represents an RTM API Rate Limit (the RTM API
+ * returned a HTTP Status code of `503`).
+ *
+ * Error Code: `-4`
+ * @returns {RTMError}
+ */
+RTMError.rateLimitError = function() {
+  return new RTMError(-4, "Rate Limit Error: Your Account has temporarily reached the RTM API Rate Limit.  Please wait a minute and try the request again later.");
+};
+
+/**
+ * Create a new `RTMError` that represents an RTM API Server Error (the RTM API
+ * returned a HTTP Status code of `5xx` - excluding `503`).
+ *
+ * Error Code: `-5`
+ * @returns {RTMError}
+ */
+RTMError.serverError = function() {
+  return new RTMError(-5, "RTM API Server Error: The RTM API Server is not responding.  Please try the request again later.");
+};
+
+module.exports = RTMError;

package/src/response/index.js

@@ -0,0 +1,8 @@
+'use strict';
+
+module.exports = {
+  error: require('./error.js'),
+  parse: require('./parse.js'),
+  response: require('./response.js'),
+  success: require('./success.js')
+};

package/src/response/parse.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const success = require('./success.js');
+const error = require('./error.js');
+
+
+/**
+ * Parse the raw RTM API Response into either a `RTMSuccess` or
+ * `RTMError` Class with the Response's properties.
+ * @param {string} raw Raw RTM API Server Response (as a JSON-formatted String)
+ * @returns {RTMError|RTMSuccess}
+ * @private
+ */
+function parse(raw) {
+
+  // Parse the response into JSON
+  let response = undefined;
+  try {
+    response = JSON.parse(raw);
+  }
+  catch(exception) {
+    return error.responseError();
+  }
+
+  // Make sure there is a response status
+  if ( !response || !response.rsp || !response.rsp.stat ) {
+    return error.responseError();
+  }
+
+  // Get the response status
+  let status = response.rsp.stat;
+
+  // SUCCESS
+  if ( status === 'ok' ) {
+    return new success(response.rsp);
+  }
+
+  // ERROR
+  else if ( status === 'fail' ) {
+    return new error(response.rsp.err.code, response.rsp.err.msg);
+  }
+
+  // UNKNOWN STATUS
+  else {
+    return error.responseError();
+  }
+
+}
+
+
+module.exports = parse;

package/src/response/response.js

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * ### RTM Generic Response
+ *
+ * This Class represents a generic Response from the RTM API Server.
+ * The `RTMError` and `RTMSuccess` Classes represent the actual failed
+ * and successful responses from the RTM API Server.
+ *
+ * This Class is extended by the {@link RTMSuccess} and {@link RTMError} Classes.
+ * @class
+ * @alias RTMResponse
+ */
+class RTMResponse {
+
+  /**
+   * Create a new Generic RTM Response with a status of either
+   * {@link RTMResponse.STATUS_OK} or {@link RTMResponse.STATUS_FAIL}.
+   * @param {string} status RTM API Status
+   * @constructor
+   */
+  constructor(status) {
+    this._status = status;
+  }
+
+  /**
+   * The RTM Response Status
+   * @type {string}
+   */
+  get status() {
+    return this._status;
+  }
+
+  /**
+   * The success of the RTM Response (ie, is `true` when status is 'ok')
+   * @type {boolean}
+   */
+  get isOk() {
+    return this._status === RTMResponse.STATUS_OK;
+  }
+
+  /**
+   * The RTM API properties of the Response
+   * @type {object}
+   */
+  get props() {
+    let rtn = {};
+    for ( let key in this ) {
+      if ( this.hasOwnProperty(key) && key !== '_status' ) {
+        rtn[key] = this[key];
+      }
+    }
+    return rtn;
+  }
+
+  /**
+   * Check if the Response has the specified property
+   * @param {string} property Property Name
+   * @returns {boolean}
+   */
+  has(property) {
+    let parts = property.split('.');
+    let object = this;
+
+    for ( let i = 0; i < parts.length; i++ ) {
+      object = object[parts[i]];
+      if ( object === undefined ) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Get a String representation of the Response
+   * @returns {string}
+   */
+  toString() {
+    return "[" + this._status + "]";
+  }
+
+}
+
+
+/**
+ * RTM Status of 'ok' = successful
+ * @type {string}
+ * @default
+ */
+RTMResponse.STATUS_OK = "ok";
+
+/**
+ * RTM Status of 'fail' = error
+ * @type {string}
+ * @default
+ */
+RTMResponse.STATUS_FAIL = "fail";
+
+
+
+module.exports = RTMResponse;

package/src/response/success.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const RTMResponse = require('./response.js');
+
+
+/**
+ * ### RTM Success Response
+ *
+ * This Class represents a successful response from the RTM API Server: the
+ * RTM API Server returned a response with a status of 'ok'. This Class will
+ * include all of the properties of the RTM `rsp` property.
+ *
+ * `RTMSuccess` extends {@link RTMResponse}
+ * @class
+ * @alias RTMSuccess
+ */
+class RTMSuccess extends RTMResponse {
+
+  /**
+   * Create a new RTM Success Response
+   * @param {object} rsp The RTM API Response's `rsp` property
+   * @constructor
+   */
+  constructor(rsp) {
+    super(RTMResponse.STATUS_OK);
+
+    // Parse the response properties
+    for ( let key in rsp ) {
+      if ( rsp.hasOwnProperty(key) && key !== 'stat' ) {
+        this[key] = rsp[key];
+      }
+    }
+  }
+
+  /**
+   * Get a String representation of the Success Response
+   * @returns {string}
+   */
+  toString() {
+    return super.toString() + " " + JSON.stringify(this.props);
+  }
+
+}
+
+
+module.exports = RTMSuccess;