Implement pagination via the scrollback() function. Update CHANGELOG.

CHANGELOG.md

@@ -15,6 +15,11 @@ Breaking changes:
    state (e.g. after calling joinRoom).
  * `MatrixClient.joinRoom` now returns a `Room` object when resolved, not an
    object with a `room_id` property.
+ * `MatrixClient.scrollback` now expects a `Room` arg instead of a `room_id`
+   and `from` token. Construct a `new Room(roomId)` if you want to continue
+   using this directly, then set the pagination token using
+   `room.oldState.paginationToken = from`. It now resolves to a `Room` object
+   instead of the raw HTTP response.
 
 New properties:
  * `User.events`

examples/node/app.js

@@ -33,7 +33,7 @@ rl.on('line', function(line) {
                 viewingRoom = room;
                 printMessages();
             }, function(err) {
-                console.log("Error: %s", err);
+                console.log("/join Error: %s", err);
             });
         }
         else {
@@ -47,6 +47,14 @@ rl.on('line', function(line) {
     else if (line === "/members" && viewingRoom) {
         printMemberList();
     }
+    else if (line.indexOf("/more ") === 0 && viewingRoom) {
+        var amount = parseInt(line.split(" ")[1]) || 20;
+        matrixClient.scrollback(viewingRoom, amount).done(function(room) {
+            printMessages();
+        }, function(err) {
+            console.log("/more Error: %s", err);
+        });
+    }
     else if (line === "/help") {
         printHelp();
     }
@@ -107,6 +115,7 @@ function printHelp() {
     console.log("Room commands:");
     console.log("  '/exit' Return to the room list index.");
     console.log("  '/members' Show the room member list.");
+    console.log("  '/more 15' Scrollback 15 events");
 }
 
 function printMessages() {
@@ -115,7 +124,7 @@ function printMessages() {
         return;
     }
     console.log(CLEAR_CONSOLE);
-    var mostRecentMessages = viewingRoom.timeline.slice(numMessagesToShow * -1);
+    var mostRecentMessages = viewingRoom.timeline;
     for (var i = 0; i < mostRecentMessages.length; i++) {
         printLine(mostRecentMessages[i]);
     }

lib/client.js

@@ -791,25 +791,36 @@ MatrixClient.prototype.roomState = function(roomId, callback) {
 };
 
 /**
- * @param {string} roomId
- * @param {string} from
- * @param {Number} limit
+ * Retrieve older messages from the given room and put them in the timeline.
+ * @param {Room} room The room to get older messages in.
+ * @param {Number} limit Optional. The maximum number of previous events to pull
+ * in.
  * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {module:client.Promise} Resolves: Room.
  * @return {module:http-api.MatrixError} Rejects: with an error response.
  */
-MatrixClient.prototype.scrollback = function(roomId, from, limit, callback) {
+MatrixClient.prototype.scrollback = function(room, limit, callback) {
     if (utils.isFunction(limit)) { callback = limit; limit = undefined; }
-    var path = utils.encodeUri("/rooms/$roomId/messages", {$roomId: roomId});
-    if (!limit) {
-        limit = 30;
-    }
+    var path = utils.encodeUri(
+        "/rooms/$roomId/messages", {$roomId: room.roomId}
+    );
     var params = {
-        from: from,
-        limit: limit,
+        from: room.oldState.paginationToken,
+        limit: (limit || 30),
         dir: 'b'
     };
-    return this._http.authedRequest(callback, "GET", path, params);
+    var defer = q.defer();
+    this._http.authedRequest(callback, "GET", path, params).done(function(res) {
+        // res.chunk end start
+        room.addEventsToTimeline(
+            utils.map(res.chunk, _PojoToMatrixEventMapper), true
+        );
+        room.oldState.paginationToken = res.end;
+        defer.resolve(room);
+    }, function(err) {
+        defer.reject(err);
+    });
+    return defer.promise;
 };
 
 // Registration/Login operations
@@ -1185,6 +1196,9 @@ function _processRoomEvents(room, stateEventList, messageChunk) {
             _PojoToMatrixEventMapper
         ).reverse(), true
     );
+    if (messageChunk) {
+        room.oldState.paginationToken = messageChunk.start;
+    }
 }
 
 /**