Bump to 0.2.2 and update CHANGELOG

CAS Auth

.gitignore

@@ -1,3 +1,4 @@
+.jsdoc
 node_modules
 .lock-wscript
 build/Release

CHANGELOG.md

@@ -1,3 +1,59 @@
+Changes in 0.2.2
+================
+
+Bug fixes:
+ * Null pointer fixes for VoIP calling and push notification processing.
+ * Set the `Content-Type` to `application/octet-stream` in the event that the
+   file object has no `type`.
+
+New methods:
+ * Added `MatrixClient.getCasServer()` which calls through to the HTTP endpoint
+   `/login/cas`.
+ * Added `MatrixClient.loginWithCas(ticket, service)` which logs in with the
+   type `m.login.cas`.
+ * Added `MatrixClient.getHomeserverUrl()` which returns the URL passed in the
+   constructor.
+ * Added `MatrixClient.getIdentityServerUrl()` which returns the URL passed in
+   the constructor.
+ * Added `getLastModifiedTime()` to `RoomMember`, `RoomState` and `User` objects.
+   This makes it easier to see if the object in question has changed, which can
+   be used to improve performance by only rendering when these objects change.
+
+Changes in 0.2.1
+================
+
+Bug fixes:
+ * The `Content-Type` of file uploads is now explicitly set, without relying
+   on the browser to do it for us.
+
+Improvements:
+ * The `MatrixScheduler.RETRY_BACKOFF_RATELIMIT` function will not retry when
+   the response is a 400,401,403.
+ * The text returned from a room invite now includes who the invite was from.
+ * There is now a try/catch block around the `request` function which will
+   reject/errback appropriately if an exception is thrown synchronously in it.
+
+Breaking changes:
+ * `MatrixClient.joinRoom` has changed from `(roomIdOrAlias, callback)` to
+   `(roomIdOrAlias, opts, callback)`.
+
+New methods:
+ * `MatrixClient.createAlias(alias, roomId)`
+ * `MatrixClient.getRoomIdForAlias(alias)`
+ * `MatrixClient.sendNotice(roomId, body, txnId, callback)`
+ * `MatrixClient.sendHtmlNotice(roomId, body, htmlBody, callback)`
+
+Modified methods:
+ * `MatrixClient.joinRoom(roomIdOrAlias, opts)` where `opts` can include a
+   `syncRoom: true|false` flag to control whether a room initial sync is
+   performed after joining the room.
+ * `MatrixClient.getAvatarUrlForMember` has a new last arg `allowDefault` which
+   returns the default identicon URL if `true`.
+ * `MatrixClient.getAvatarUrlForRoom` has a new last arg `allowDefault` which
+   is passed through to the default identicon generation for
+   `getAvatarUrlForMember`.
+
+
 Changes in 0.2.0
 ================
 

README.md

@@ -105,7 +105,7 @@ you'll see used is:
 The ``callback`` parameter is optional, so you could do:
 
 ```javascript
-  matrixClient.someMethod(arg1, arg2).then(function(result) {
+  matrixClient.someMethod(arg1, arg2).then(function(err, result) {
     ...
   });
 ```
@@ -216,20 +216,18 @@ API Reference
 =============
 
 A hosted reference can be found at
-http://matrix-org.github.io/matrix-js-sdk/global.html
+http://matrix-org.github.io/matrix-js-sdk/index.html
 
 This SDK uses JSDoc3 style comments. You can manually build and
 host the API reference from the source files like this:
 
 ```
-  $ npm install -g jsdoc
-  $ jsdoc -r lib/
-  $ cd out
+  $ npm run gendoc
+  $ cd .jsdoc
   $ python -m SimpleHTTPServer 8005
 ```
   
-Then visit ``http://localhost:8005`` to see the API docs. By
-default, ``jsdoc`` produces HTML in the ``out`` folder.
+Then visit ``http://localhost:8005`` to see the API docs.
 
 Contributing
 ============
@@ -259,7 +257,7 @@ To run tests (Jasmine)::
  $ npm test
 ```
  
-To run linters (Google Closure Linter and JSHint):
+To run linting:
 ```
  $ npm run lint
 ```

lib/client.js

@@ -64,6 +64,9 @@ var OLM_ALGORITHM = "m.olm.v1.curve25519-aes-sha2";
 function MatrixClient(opts) {
     utils.checkObjectHasKeys(opts, ["baseUrl", "request"]);
 
+    this.baseUrl = opts.baseUrl;
+    this.idBaseUrl = opts.idBaseUrl;
+
     this.store = opts.store || new StubStore();
     this.sessionStore = opts.sessionStore || null;
     this.accountKey = "DEFAULT_KEY";
@@ -150,6 +153,21 @@ function MatrixClient(opts) {
 }
 utils.inherits(MatrixClient, EventEmitter);
 
+/**
+ * Get the Homserver URL of this client
+ * @return {string} Homeserver URL of this client
+ */
+MatrixClient.prototype.getHomeserverUrl = function() {
+    return this.baseUrl;
+};
+
+/**
+ * Get the Identity Server URL of this client
+ * @return {string} Identity Server URL of this client
+ */
+MatrixClient.prototype.getIdentityServerUrl = function() {
+    return this.idBaseUrl;
+};
 
 /**
  * Is end-to-end crypto enabled for this client.
@@ -502,11 +520,22 @@ MatrixClient.prototype.createRoom = function(options, callback) {
 /**
  * Join a room. If you have already joined the room, this will no-op.
  * @param {string} roomIdOrAlias The room ID or room alias to join.
+ * @param {Object} opts Options when joining the room.
+ * @param {boolean} opts.syncRoom True to do a room initial sync on the resulting
+ * room. If false, the <strong>returned Room object will have no current state.
+ * </strong> Default: true.
  * @param {module:client.callback} callback Optional.
  * @return {module:client.Promise} Resolves: Room object.
  * @return {module:http-api.MatrixError} Rejects: with an error response.
  */
-MatrixClient.prototype.joinRoom = function(roomIdOrAlias, callback) {
+MatrixClient.prototype.joinRoom = function(roomIdOrAlias, opts, callback) {
+    // to help people when upgrading..
+    if (utils.isFunction(opts)) {
+        throw new Error("Expected 'opts' object, got function.");
+    }
+    opts = opts || {
+        syncRoom: true
+    };
     var room = this.getRoom(roomIdOrAlias);
     if (room && room.hasMembershipState(this.credentials.userId, "join")) {
         return q(room);
@@ -518,7 +547,10 @@ MatrixClient.prototype.joinRoom = function(roomIdOrAlias, callback) {
     function(res) {
         var roomId = res.room_id;
         var room = createNewRoom(self, roomId);
-        return _syncRoom(self, room);
+        if (opts.syncRoom) {
+            return _syncRoom(self, room);
+        }
+        return q(room);
     }, function(err) {
         _reject(callback, defer, err);
     }).done(function(room) {
@@ -1003,6 +1035,22 @@ MatrixClient.prototype.sendTextMessage = function(roomId, body, txnId, callback)
     return this.sendMessage(roomId, content, txnId, callback);
 };
 
+/**
+ * @param {string} roomId
+ * @param {string} body
+ * @param {string} txnId Optional.
+ * @param {module:client.callback} callback Optional.
+ * @return {module:client.Promise} Resolves: TODO
+ * @return {module:http-api.MatrixError} Rejects: with an error response.
+ */
+MatrixClient.prototype.sendNotice = function(roomId, body, txnId, callback) {
+    var content = {
+         msgtype: "m.notice",
+         body: body
+    };
+    return this.sendMessage(roomId, content, txnId, callback);
+};
+
 /**
  * @param {string} roomId
  * @param {string} body
@@ -1058,6 +1106,24 @@ MatrixClient.prototype.sendHtmlMessage = function(roomId, body, htmlBody, callba
     return this.sendMessage(roomId, content, callback);
 };
 
+/**
+ * @param {string} roomId
+ * @param {string} body
+ * @param {string} htmlBody
+ * @param {module:client.callback} callback Optional.
+ * @return {module:client.Promise} Resolves: TODO
+ * @return {module:http-api.MatrixError} Rejects: with an error response.
+ */
+MatrixClient.prototype.sendHtmlNotice = function(roomId, body, htmlBody, callback) {
+    var content = {
+        msgtype: "m.notice",
+        format: "org.matrix.custom.html",
+        body: body,
+        formatted_body: htmlBody
+    };
+    return this.sendMessage(roomId, content, callback);
+};
+
 /**
  * Upload a file to the media repository on the home server.
  * @param {File} file object
@@ -1093,6 +1159,42 @@ MatrixClient.prototype.sendTyping = function(roomId, isTyping, timeoutMs, callba
     );
 };
 
+/**
+ * Create an alias to room ID mapping.
+ * @param {string} alias The room alias to create.
+ * @param {string} roomId The room ID to link the alias to.
+ * @param {module:client.callback} callback Optional.
+ * @return {module:client.Promise} Resolves: TODO.
+ * @return {module:http-api.MatrixError} Rejects: with an error response.
+ */
+MatrixClient.prototype.createAlias = function(alias, roomId, callback) {
+    var path = utils.encodeUri("/directory/room/$alias", {
+        $alias: alias
+    });
+    var data = {
+        room_id: roomId
+    };
+    return this._http.authedRequest(
+        callback, "PUT", path, undefined, data
+    );
+};
+
+/**
+ * Get room info for the given alias.
+ * @param {string} alias The room alias to resolve.
+ * @param {module:client.callback} callback Optional.
+ * @return {module:client.Promise} Resolves: Object with room_id and servers.
+ * @return {module:http-api.MatrixError} Rejects: with an error response.
+ */
+MatrixClient.prototype.getRoomIdForAlias = function(alias, callback) {
+    var path = utils.encodeUri("/directory/room/$alias", {
+        $alias: alias
+    });
+    return this._http.authedRequest(
+        callback, "GET", path
+    );
+};
+
 /**
  * @param {string} roomId
  * @param {string} eventId
@@ -1309,17 +1411,21 @@ MatrixClient.prototype.setAvatarUrl = function(url, callback) {
  * @param {Number} height The desired height of the thumbnail.
  * @param {string} resizeMethod The thumbnail resize method to use, either
  * "crop" or "scale".
+ * @param {Boolean} allowDefault (optional) Passing false causes this method to
+ * return null if the user has no avatar image. Otherwise, a default image URL
+ * will be returned.
  * @return {?string} the avatar URL or null.
  */
 MatrixClient.prototype.getAvatarUrlForMember =
-        function(member, width, height, resizeMethod) {
+        function(member, width, height, resizeMethod, allowDefault) {
     if (!member || !member.events.member) {
         return null;
     }
+    if (allowDefault === undefined) { allowDefault = true; }
     var rawUrl = member.events.member.getContent().avatar_url;
     if (rawUrl) {
         return this._http.getHttpUriForMxc(rawUrl, width, height, resizeMethod);
-    } else {
+    } else if (allowDefault) {
         return this._http.getIdenticonUri(member.userId, width, height);
     }
     return null;
@@ -1333,10 +1439,13 @@ MatrixClient.prototype.getAvatarUrlForMember =
  * @param {Number} height The desired height of the thumbnail.
  * @param {string} resizeMethod The thumbnail resize method to use, either
  * "crop" or "scale".
+ * @param {Boolean} allowDefault (optional) Passing false causes this method to
+ * return null if the user has no avatar image. Otherwise, a default image URL
+ * will be returned.
  * @return {?string} the avatar URL or null.
  */
 MatrixClient.prototype.getAvatarUrlForRoom =
-        function(room, width, height, resizeMethod) {
+        function(room, width, height, resizeMethod, allowDefault) {
 
     if (!room || !room.currentState || !room.currentState.members) {
         return null;
@@ -1348,7 +1457,9 @@ MatrixClient.prototype.getAvatarUrlForRoom =
     });
 
     if (members[0]) {
-        return this.getAvatarUrlForMember(members[0], width, height, resizeMethod);
+        return this.getAvatarUrlForMember(
+            members[0], width, height, resizeMethod, allowDefault
+        );
     }
     return null;
 };
@@ -1625,6 +1736,31 @@ MatrixClient.prototype.loginWithSAML2 = function(relayState, callback) {
     }, callback);
 };
 
+/**
+ * @param {module:client.callback} callback Optional.
+ * @return {module:client.Promise} Resolves: TODO
+ * @return {module:http-api.MatrixError} Rejects: with an error response.
+ */
+MatrixClient.prototype.getCasServer = function(callback) {
+    return this._http.request(
+        callback, "GET", "/login/cas", undefined, undefined
+    );
+};
+
+/**
+ * @param {string} ticket (Received from CAS)
+ * @param {string} service Service to which the token was granted
+ * @param {module:client.callback} callback Optional.
+ * @return {module:client.Promise} Resolves: TODO
+ * @return {module:http-api.MatrixError} Rejects: with an error response.
+ */
+MatrixClient.prototype.loginWithCas = function(ticket, service, callback) {
+    return this.login("m.login.cas", {
+        ticket: ticket,
+        service: service
+    }, callback);
+};
+
 // Push operations
 // ===============
 
@@ -2362,7 +2498,7 @@ module.exports.CRYPTO_ENABLED = CRYPTO_ENABLED;
 /**
  * Fires whenever an incoming call arrives.
  * @event module:client~MatrixClient#"Call.incoming"
- * @param {MatrixCall} call The incoming call.
+ * @param {module:webrtc/call~MatrixCall} call The incoming call.
  * @example
  * matrixClient.on("Call.incoming", function(call){
  *   call.answer(); // auto-answer

lib/http-api.js

@@ -205,6 +205,13 @@ module.exports.MatrixHttpApi.prototype = {
             url += "&filename=" + encodeURIComponent(file.name);
 
             xhr.open("POST", url);
+            if (file.type) {
+                xhr.setRequestHeader("Content-Type", file.type);
+            } else {
+                // if the file doesn't have a mime type, use a default since
+                // the HS errors if we don't supply one.
+                xhr.setRequestHeader("Content-Type", 'application/octet-stream');
+            }
             xhr.send(file);
         } else {
             var queryParams = {
@@ -375,23 +382,38 @@ module.exports.MatrixHttpApi.prototype = {
             }
         }
         var defer = q.defer();
-        this.opts.request(
-            {
-                uri: uri,
-                method: method,
-                withCredentials: false,
-                qs: queryParams,
-                body: data,
-                json: true,
-                _matrix_opts: this.opts
-            },
-            requestCallback(defer, callback, this.opts.onlyData)
-        );
+        try {
+            this.opts.request(
+                {
+                    uri: uri,
+                    method: method,
+                    withCredentials: false,
+                    qs: queryParams,
+                    body: data,
+                    json: true,
+                    _matrix_opts: this.opts
+                },
+                requestCallback(defer, callback, this.opts.onlyData)
+            );
+        }
+        catch (ex) {
+            defer.reject(ex);
+            if (callback) {
+                callback(ex);
+            }
+        }
         return defer.promise;
     }
 };
 
-
+/*
+ * Returns a callback that can be invoked by an HTTP request on completion,
+ * that will either resolve or reject the given defer as well as invoke the
+ * given userDefinedCallback (if any).
+ *
+ * If onlyData is true, the defer/callback is invoked with the body of the
+ * response, otherwise the result code.
+ */
 var requestCallback = function(defer, userDefinedCallback, onlyData) {
     userDefinedCallback = userDefinedCallback || function() {};
 
@@ -422,12 +444,14 @@ var requestCallback = function(defer, userDefinedCallback, onlyData) {
  * 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} errcode The Matrix 'errcode' value, e.g. "M_FORBIDDEN".
+ * @prop {string} name Same as MatrixError.errcode but with a default unknown string.
  * @prop {string} message The Matrix 'error' value, e.g. "Missing token."
  * @prop {Object} data The raw Matrix error JSON used to construct this object.
  * @prop {integer} httpStatus The numeric HTTP status code given
  */
 module.exports.MatrixError = function MatrixError(errorJson) {
+    this.errcode = errorJson.errcode;
     this.name = errorJson.errcode || "Unknown error code";
     this.message = errorJson.error || "Unknown message";
     this.data = errorJson;

lib/models/room-member.js

@@ -35,6 +35,7 @@ function RoomMember(roomId, userId) {
     this.events = {
         member: null
     };
+    this._updateModifiedTime();
 }
 utils.inherits(RoomMember, EventEmitter);
 
@@ -59,9 +60,11 @@ RoomMember.prototype.setMembershipEvent = function(event, roomState) {
     var oldName = this.name;
     this.name = calculateDisplayName(this, event, roomState);
     if (oldMembership !== this.membership) {
+        this._updateModifiedTime();
         this.emit("RoomMember.membership", event, this);
     }
     if (oldName !== this.name) {
+        this._updateModifiedTime();
         this.emit("RoomMember.name", event, this);
     }
 };
@@ -96,6 +99,7 @@ RoomMember.prototype.setPowerLevelEvent = function(powerLevelEvent) {
     // emit for changes in powerLevelNorm as well (since the app will need to
     // redraw everyone's level if the max has changed)
     if (oldPowerLevel !== this.powerLevel || oldPowerLevelNorm !== this.powerLevelNorm) {
+        this._updateModifiedTime();
         this.emit("RoomMember.powerLevel", powerLevelEvent, this);
     }
 };
@@ -121,10 +125,28 @@ RoomMember.prototype.setTypingEvent = function(event) {
         this.typing = true;
     }
     if (oldTyping !== this.typing) {
+        this._updateModifiedTime();
         this.emit("RoomMember.typing", event, this);
     }
 };
 
+/**
+ * Update the last modified time to the current time.
+ */
+RoomMember.prototype._updateModifiedTime = function() {
+    this._modified = Date.now();
+};
+
+/**
+ * Get the timestamp when this RoomMember was last updated. This timestamp is
+ * updated when properties on this RoomMember are updated.
+ * It is updated <i>before</i> firing events.
+ * @return {number} The timestamp
+ */
+RoomMember.prototype.getLastModifiedTime = function() {
+    return this._modified;
+};
+
 function calculateDisplayName(member, event, roomState) {
     var displayName = event.getDirectionalContent().displayname;
     var selfUserId = member.userId;

lib/models/room-state.js

@@ -30,6 +30,7 @@ function RoomState(roomId) {
     this._sentinels = {
         // userId: RoomMember
     };
+    this._updateModifiedTime();
 }
 utils.inherits(RoomState, EventEmitter);
 
@@ -96,6 +97,7 @@ RoomState.prototype.getStateEvents = function(eventType, stateKey) {
  */
 RoomState.prototype.setStateEvents = function(stateEvents) {
     var self = this;
+    this._updateModifiedTime();
 
     // update the core event dict
     utils.forEach(stateEvents, function(event) {
@@ -162,6 +164,22 @@ RoomState.prototype.setTypingEvent = function(event) {
     });
 };
 
+/**
+ * Update the last modified time to the current time.
+ */
+RoomState.prototype._updateModifiedTime = function() {
+    this._modified = Date.now();
+};
+
+/**
+ * Get the timestamp when this room state was last updated. This timestamp is
+ * updated when this object has received new state events.
+ * @return {number} The timestamp
+ */
+RoomState.prototype.getLastModifiedTime = function() {
+    return this._modified;
+};
+
 /**
  * The RoomState class.
  */

lib/models/room.js

@@ -278,7 +278,13 @@ function calculateRoomName(room, userId) {
             if (memberList.length === 1) {
                 // we exist, but no one else... self-chat or invite.
                 if (memberList[0].membership === "invite") {
-                    return "Room Invite";
+                    if (memberList[0].events.member) {
+                        // extract who invited us to the room
+                        return "Invite from " + memberList[0].events.member.getSender();
+                    }
+                    else {
+                        return "Room Invite";
+                    }
                 }
                 else {
                     return userId;

lib/models/user.js

@@ -29,6 +29,7 @@ function User(userId) {
         presence: null,
         profile: null
     };
+    this._updateModifiedTime();
 }
 utils.inherits(User, EventEmitter);
 
@@ -64,11 +65,32 @@ User.prototype.setPresenceEvent = function(event) {
     this.avatarUrl = event.getContent().avatar_url;
     this.lastActiveAgo = event.getContent().last_active_ago;
 
+    if (eventsToFire.length > 0) {
+        this._updateModifiedTime();
+    }
+
     for (var i = 0; i < eventsToFire.length; i++) {
         this.emit(eventsToFire[i], event, this);
     }
 };
 
+/**
+ * Update the last modified time to the current time.
+ */
+User.prototype._updateModifiedTime = function() {
+    this._modified = Date.now();
+};
+
+/**
+ * Get the timestamp when this User was last updated. This timestamp is
+ * updated when this User receives a new Presence event which has updated a
+ * property on this object. It is updated <i>before</i> firing events.
+ * @return {number} The timestamp
+ */
+User.prototype.getLastModifiedTime = function() {
+    return this._modified;
+};
+
 /**
  * The User class.
  */

lib/pushprocessor.js

@@ -140,7 +140,8 @@ function PushProcessor(client) {
         }
 
         var room = client.getRoom(ev.room_id);
-        if (!room || !room.currentState || !room.currentState.members) { return false; }
+        if (!room || !room.currentState || !room.currentState.members ||
+            !room.currentState.getMember(client.credentials.userId)) { return false; }
 
         var displayName = room.currentState.getMember(client.credentials.userId).name;
 

lib/scheduler.js

@@ -129,6 +129,10 @@ MatrixScheduler.prototype.queueEvent = function(event) {
  * @see module:scheduler~retryAlgorithm
  */
 MatrixScheduler.RETRY_BACKOFF_RATELIMIT = function(event, attempts, err) {
+    if (err.httpStatus === 400 || err.httpStatus === 403 || err.httpStatus === 401) {
+        // client error; no amount of retrying with save you now.
+        return -1;
+    }
     if (err.name === "M_LIMIT_EXCEEDED") {
         var waitTime = err.data.retry_after_ms;
         if (waitTime) {

lib/webrtc/call.js

@@ -156,7 +156,11 @@ MatrixCall.prototype._initWithInvite = function(event) {
     // firefox and OpenWebRTC's RTCPeerConnection doesn't add streams until it
     // starts getting media on them so we need to figure out whether a video
     // channel has been offered by ourselves.
-    if (this.msg.offer.sdp.indexOf('m=video') > -1) {
+    if (
+        this.msg.offer &&
+        this.msg.offer.sdp &&
+        this.msg.offer.sdp.indexOf('m=video') > -1
+    ) {
         this.type = 'video';
     }
     else {

package.json

@@ -1,11 +1,12 @@
 {
   "name": "matrix-js-sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Matrix Client-Server SDK for Javascript",
   "main": "index.js",
   "scripts": {
     "test": "istanbul cover --report cobertura --config .istanbul.yml -i \"lib/**/*.js\" jasmine-node -- spec --verbose --junitreport --forceexit --captureExceptions",
     "check": "jasmine-node spec --verbose --junitreport --forceexit --captureExceptions",
+    "gendoc": "jsdoc -r lib -P package.json -R README.md -d .jsdoc",
     "build": "jshint -c .jshint lib/ && browserify browser-index.js -o dist/browser-matrix-dev.js --ignore-missing",
     "watch": "watchify browser-index.js -o dist/browser-matrix-dev.js -v",
     "lint": "jshint -c .jshint lib spec && gjslint --unix_mode --disable 0131,0211,0200,0222 --max_line_length 90 -r spec/ -r lib/",

spec/integ/matrix-client-room-timeline.spec.js

@@ -280,11 +280,12 @@ describe("MatrixClient room timelines", function() {
 
                 client.scrollback(room, 1).done(function() {
                     expect(room.oldState.paginationToken).toEqual(sbEndTok);
-                    done();
                 });
 
                 httpBackend.flush("/messages", 1);
-                httpBackend.flush("/events", 1);
+                httpBackend.flush("/events", 1).done(function() {
+                     done();
+                 });
             });
             httpBackend.flush("/initialSync", 1);
         });

spec/unit/pushprocessor.spec.js

@@ -208,7 +208,6 @@ describe('NotificationService', function() {
             }
         });
         pushProcessor = new PushProcessor(matrixClient);
-        console.log("badger: " + JSON.stringify(pushProcessor));
     });
 
     // User IDs