Add MatrixError class. More jsdoc voodoo to get things looking right.

lib/client.js

@@ -13,14 +13,18 @@ var utils = require("./utils");
 // Internal: rate limiting
 
 /**
- * The standard MatrixClient callback interface.
+ * The standard MatrixClient callback interface. Functions which accept this
+ * will specify 2 return arguments. These arguments map to the 2 parameters
+ * specified in this callback.
  * @callback module:client.callback
- * @param {Object} err The error value or null.
- * @param {Object} data The data returned.
+ * @param {Object} err The error value, the "rejected" value or null.
+ * @param {Object} data The data returned, the "resolved" value.
  */
 
  /**
-  * {@link https://github.com/kriskowal/q|A promise implementation (Q)}.
+  * {@link https://github.com/kriskowal/q|A promise implementation (Q)}. Functions
+  * which return this will specify 2 return arguments. These arguments map to the
+  * "onFulfilled" and "onRejected" values of the Promise.
   * @typedef {Object} Promise
   * @static
   * @property {Function} then promise.then(onFulfilled, onRejected, onProgress)
@@ -35,7 +39,6 @@ var utils = require("./utils");
  * @param {Object} opts The configuration options for this client.
  * @param {string} opts.baseUrl Required. The base URL to the client-server HTTP API.
  * @param {Function} opts.request Required. The function to invoke for HTTP requests.
- * @param {boolean} opts.usePromises True to use promises rather than callbacks.
  * @param {string} opts.accessToken The access_token for this user.
  * @param {string} opts.userId The user ID for this user.
  * @param {Object} opts.store Optional. The data store to use. Defaults to
@@ -44,7 +47,7 @@ var utils = require("./utils");
 module.exports.MatrixClient = function MatrixClient(opts) {
     utils.checkObjectHasKeys(opts, ["baseUrl", "request"]);
     utils.checkObjectHasNoAdditionalKeys(opts,
-        ["baseUrl", "request", "usePromises", "accessToken", "userId", "store"]
+        ["baseUrl", "request", "accessToken", "userId", "store"]
     );
 
     this.store = opts.store || new MatrixInMemoryStore();
@@ -77,9 +80,10 @@ module.exports.MatrixClient.prototype = {
      * @param {string[]} options.invite A list of user IDs to invite to this room.
      * @param {string} options.name The name to give this room.
      * @param {string} options.topic The topic to give this room.
-     * @param {module:client.callback} callback Optional. The callback to invoke.
-     * @return {(module:client.Promise|undefined)} A Promise if a callback is
-     * not specified.
+     * @param {module:client.callback} callback Optional.
+     * @return {module:client.Promise} Resolves: <code>{room_id: {string}, 
+     * room_alias: {string(opt)}}</code>
+     * @return {module:http-api.MatrixError} Rejects: with the error response.
      */
     createRoom: function(options, callback) {
         // valid options include: room_alias_name, visibility, invite

lib/http-api.js

@@ -189,10 +189,27 @@ var requestCallback = function(userDefinedCallback) {
             return userDefinedCallback(err);
         }
         if (response.statusCode >= 400) {
-            return userDefinedCallback(body);
+            return userDefinedCallback(new Error(body));
         }
         else {
             userDefinedCallback(null, body);
         }
     };
 };
+
+/**
+ * Construct a Matrix error. This is a JavaScript Error with additional
+ * information specific to the standard Matrix error response.
+ * @constructor
+ * @param {Object} errorJson The Matrix error JSON returned from the homeserver.
+ * @prop {string} name The Matrix 'errcode' value, e.g. "M_FORBIDDEN".
+ * @prop {string} message The Matrix 'error' value, e.g. "Missing token."
+ * @prop {Object} data The raw Matrix error JSON used to construct this object.
+ */
+module.exports.MatrixError = function MatrixError(errorJson) {
+    this.name = errorJson.errcode || "Unknown error code";
+    this.message = errorJson.error || "Unknown message";
+    this.data = errorJson;
+}
+module.exports.MatrixError.prototype = Object.create(Error.prototype);
+module.exports.MatrixError.prototype.constructor = MatrixError;

lib/matrix.js

@@ -6,6 +6,8 @@ module.exports.MatrixEvent = require("./models/event").MatrixEvent;
 module.exports.MatrixInMemoryStore = require("./store/memory");
 /** The {@link module:http-api.MatrixHttpApi|MatrixHttpApi} class. */
 module.exports.MatrixHttpApi = require("./http-api").MatrixHttpApi;
+/** The {@link module:http-api.MatrixError|MatrixError} class. */
+module.exports.MatrixError = require("./http-api").MatrixError;
 /** The {@link module:client.MatrixClient|MatrixClient} class. */
 module.exports.MatrixClient = require("./client").MatrixClient;