Merge pull request #207 from opentok/dev

v2.9.0

.travis.yml

@@ -4,6 +4,9 @@ node_js:
 - 5
 - 6
 - 7
+- 8
+- 9
+- 10
 before_script:
 - npm install -g grunt-cli
 notifications:

README.md

@@ -310,6 +310,24 @@ You can also call the `stop()` method of the Broadcast object to stop a broadcas
 
 Call the `Opentok.getBroadcast()` method, passing in a broadcast ID, to get a Broadcast object.
 
+You can also get a list of all the Broadcasts you've created (up to 1000) with your API Key. This is
+done using the `OpenTok.listBroadcasts(options, callback)` method. The parameter `options` is an
+optional object used to specify an `offset`, `count`, and `sessionId` to help you paginate through the results.
+The callback has a signature `function(err, broadcasts, totalCount)`. The `broadcasts` returned from
+the callback is an array of `Broadcast` instances. The `totalCount` returned from the callback is
+the total number of broadcasts your API Key has generated.
+
+```javascript
+opentok.listBroadcasts({offset:100, count:50}, function(error, broadcasts, totalCount) {
+  if (error) return console.log("error:", error);
+
+  console.log(totalCount + " broadcasts");
+  for (var i = 0; i < broadcasts.length; i++) {
+    console.log(broadcasts[i].id);
+  }
+});
+```
+
 To change the broadcast layout, call the `OpenTok.setBroadcastLayout()` method,
 passing in the broadcast ID and the [layout
 type](https://tokbox.com/developer/guides/broadcast/live-streaming/#configuring-video-layout-for-opentok-live-streaming-broadcasts).

lib/client.js

@@ -4,6 +4,7 @@ var _ = require('lodash');
 var generateJwt = require('./generateJwt');
 var pkg = require('../package.json');
 var Stream = require('./stream');
+var Broadcast = require('./broadcast');
 var defaultConfig = {
   apiKey: null,
   apiSecret: null,
@@ -18,7 +19,8 @@ var defaultConfig = {
     startBroadcast: '/v2/project/<%apiKey%>/broadcast',
     stopBroadcast: '/v2/project/<%apiKey%>/broadcast/<%broadcastId%>/stop',
     getBroadcast: '/v2/project/<%apiKey%>/broadcast/<%broadcastId%>',
-    setBroadcastLayout: '/v2/project/<%apiKey%>/broadcast/<%broadcastId%>/layout'
+    setBroadcastLayout: '/v2/project/<%apiKey%>/broadcast/<%broadcastId%>/layout',
+    listBroadcasts: '/v2/project/<%apiKey%>/broadcast'
   },
   request: {
     timeout: 20000 // 20 seconds
@@ -167,6 +169,27 @@ Client.prototype.getBroadcast = function getBroadcast(broadcastId, cb) {
   });
 };
 
+Client.prototype.listBroadcasts = function listBroadcasts(queryString, cb) {
+  var baseUrl = this.c.apiUrl + this.c.endpoints.listBroadcasts.replace(/<%apiKey%>/g, this.c.apiKey);
+  var url = queryString.length > 0 ? baseUrl + '?' + queryString : baseUrl;
+  var parsedBody;
+  request.get({
+    url: url,
+    headers: this.generateHeaders()
+  }, function requestCallback(err, resp, body) {
+    if (err) {
+      return cb(new Error('The request failed: ' + err));
+    }
+    if (resp.statusCode === 200) {
+      parsedBody = JSON.parse(body);
+      return cb(null, parsedBody.items.map(function itemIterator(item) {
+        return new Broadcast(Client, JSON.stringify(item));
+      }), parsedBody.count);
+    }
+    return cb(new Error('(' + resp.statusCode + ') ' + body ? body.message : ''));
+  });
+};
+
 Client.prototype.setBroadcastLayout = function setBroadcastLayout(opts, cb) {
   var url = this.c.apiUrl + this.c.endpoints.setBroadcastLayout
     .replace(/<%apiKey%>/g, this.c.apiKey)

lib/opentok.js

@@ -288,8 +288,8 @@ OpenTok = function (apiKey, apiSecret, env) {
   *   </li>
   *
   *   <li>
-  *     <code>sessionId</code> &mdash; Specify the id of a session in order to retrieve archives
-  *     specifically for that session. This property is optional. When no sessionId is specified,
+  *     <code>sessionId</code> &mdash; Specify the ID of a session in order to retrieve archives
+  *     specifically for that session. This property is optional. When no session ID is specified,
   *     then the method will return archives from any session created with your API key.
   *   </li>
   *
@@ -418,7 +418,7 @@ OpenTok = function (apiKey, apiSecret, env) {
    *      <code>startBroadcast()</code> method and the
    *      {@link OpenTok#getBroadcast OpenTok.getBroadcast()} method. OpenTok streams
    *      the session to each RTMP URL you specify. Note that OpenTok live streaming
-   *      does not support RTMPS.
+   *      supports RTMP and RTMPS.
    *      </p>
    *      <p>
    *      For HLS, include a single <code>hls</code> property of the <code>outputs</code> object.
@@ -542,6 +542,81 @@ OpenTok = function (apiKey, apiSecret, env) {
     });
   };
 
+  /**
+  * Retrieves a List of {@link Broadcast} objects, representing broadcasts that are both
+  * completed and in-progress, for your API key.
+  *
+  * @param options {Object} An options parameter with three properties:
+  *
+  * <ul>
+  *
+  *   <li>
+  *     <code>count</code> &mdash; The maximum number of broadcasts to return. The default number of
+  *     broadcasts returned is 50 (or fewer, if there are fewer than 50 broadcasts).
+  *     The method returns a maximum of 1000 broadcasts.
+  *   </li>
+  *
+  *   <li>
+  *     <code>offset</code> &mdash; The offset for the first broadcast to list (starting with the
+  *     first broadcast recorded as offset 0). 1 is the offset of the broadcast that started prior
+  *     to the most recent broadcast. This property is optional; the default is 0.
+  *   </li>
+  *
+  *   <li>
+  *     <code>sessionId</code> &mdash; Specify the ID of a session in order to retrieve broadcasts
+  *     specifically for that session. This property is optional. When no session ID is specified,
+  *     then the method will return broadcasts from any session created with your API key.
+  *   </li>
+  *
+  * </ul>
+  *
+  * <p>If you don't pass in an <code>options</code> argument,
+  * the method returns up to 1000 broadcasts starting with the first broadcast recorded.
+  *
+  * @param callback {Function} The function to call upon completing the operation. Two arguments
+  * are passed to the function:
+  *
+  * <ul>
+  *
+  *   <li>
+  *      <code>error</code> &mdash; An error object (if the call to the method fails).
+  *   </li>
+  *
+  *   <li>
+  *       <code>broadcasts</code> &mdash; An array of {@link Broadcast} objects.
+  *   </li>
+  *
+  * </ul>
+  *
+  * @method #listBroadcasts
+  * @memberof OpenTok
+  */
+  this.listBroadcasts = function listBroadcasts(options, callback) {
+    var query = [];
+    var queryString = null;
+    if (typeof options === 'function') {
+      callback = options;
+      options = {};
+    }
+    if (typeof callback !== 'function') {
+      throw (new errors.ArgumentError('No callback given to listBroadcasts'));
+    }
+    if (options.offset) {
+      query.push('offset=' + parseInt(options.offset, 10));
+    }
+    if (options.count) {
+      query.push('count=' + parseInt(options.count, 10));
+    }
+    if (options.sessionId) {
+      query.push('sessionId=' + options.sessionId);
+    }
+    queryString = query.join('&');
+    return this.client.listBroadcasts(queryString, function cb(err, json, totalCount) {
+      if (err) { return callback(err); }
+      return callback(null, json, totalCount);
+    });
+  };
+
   /**
    * Sets (or updates) the layout of the broadcast. See
    * <a href="https://tokbox.com/developer/guides/broadcast/live-streaming/#configuring-video-layout-for-opentok-live-streaming-broadcasts">
@@ -819,7 +894,8 @@ OpenTok = function (apiKey, apiSecret, env) {
   *
   * @param sipUri The sip URI the SIP Interconnect feature will dial.
   *
-  * @param options {Object} An optional options object with the following properties (all of which are optional):
+  * @param options {Object} An optional options object with the following properties
+  * (all of which are optional):
   * <p>
   * <ul>
   *   <li>
@@ -840,10 +916,15 @@ OpenTok = function (apiKey, apiSecret, env) {
   *     encrypted or not.
   *   </li>
   *   <li>
-  *     <code>from</code> (String) &mdash; The number or string that will be sent to the final SIP number as the caller. It must be a string in the form of 
-  *     <code>[email protected]</code>, where <code>from</code> can be a string or a number. 
-  *     If <code>from</code> is set to a number (for example, <code>"[email protected]"</code>), it will show up as the incoming number on PSTN phones. 
-  *     If <code>from</code> is undefined or set to a string (for example, <code>"[email protected]"</code>), <code>+00000000</code> will show up as the incoming number on PSTN phones.
+  *     <code>from</code> (String) &mdash; The number or string that will be sent
+  *     to the final SIP number as the caller. It must be a string in the form of
+  *     <code>[email protected]</code>, where <code>from</code> can be a string or a number.
+  *     If <code>from</code> is set to a number (for example,
+  *     <code>"[email protected]"</code>),
+  *     it will show up as the incoming number on PSTN phones.
+  *     If <code>from</code> is undefined or set to a string (for example,
+  *     <code>"[email protected]"</code>),
+  *     <code>+00000000</code> will show up as the incoming number on PSTN phones.
   *   </li>
   * </ul>
   *