Merge pull request #195 from slackhq/update_api_facets

Updates the API facets to add new endpoints, fix a couple of bad args…

CHANGELOG.md

@@ -1,3 +1,24 @@
+### v3.0.0 (2016-04-24)
+
+  * Adds a number of new web client API facets:
+    - [`dnd`](/lib/clients/web/facets/dnd.js)
+    - [`files.comments`](/lib/clients/web/facets/files.comments.js)
+    - [`mpim`](/lib/clients/web/facets/mpim.js)
+    - [`usergroups`](/lib/clients/web/facets/usergroups.js)
+    - [`usergroups.users`](/lib/clients/web/facets/usergroups.users.js)
+  * **BREAKING** Changes the function signatures for some facet methods:
+    - [`channels.list`](/lib/clients/web/facets/channels.js): `exclude_archived` moves to an `opts` object, instead of being a separate argument
+    - [`groups.list`](/lib/clients/web/facets/groups.js): `exclude_archived` moves to an `opts` object, instead of being a separate argument
+    - [`chat.delete`](/lib/clients/web/facets/chat.js): The `ts` and `channel` arguments are re-ordered to be alphabetical
+    - [`stars.list`](/lib/clients/web/facets/stars.js): `user` moves to an `opts` object, instead of being a separate argument
+    - [`users.list`](/lib/clients/web/facets/users.js): `presence` moves to an `opts` object, instead of being a separate argument
+  * **BREAKING** Updates the function signature for [`BaseAPIClient.prototype.makeAPICall`](/lib/clients/client.js) to take required API args and optional API args as separate params, from `makeAPICall(endpoint, optData, optCb)` to `makeAPICall(endpoint, apiArgs, apiOptArgs, optCb)`
+  * New methods are added to various facets:
+    - [`files.revokePublicURL`](/lib/clients/web/facets/files.js)
+    - [`files.sharedPublicURL`](/lib/clients/web/facets/files.js)
+    - [`team.integrationLogs`](/lib/clients/web/facets/team.js)
+    - [`team.integrationLogs`](/lib/clients/web/facets/team.js)
+
 ### v2.3.0 (2016-02-28)
 
   * Caches messages on the RTM client, to improve handling in cases where message send fails

lib/clients/client.js

@@ -134,24 +134,23 @@ BaseAPIClient.prototype._callTransport = function _callTransport(task, queueCb)
  * Makes a call to the Slack API.
  *
  * @param {String} endpoint The API endpoint to send to.
- * @param {Object=} optData The data send to the Slack API.
+ * @param {Object=} apiArgs
+ * @param {Object=} apiOptArgs
  * @param {function=} optCb The callback to run on completion.
+ * @private
  */
-BaseAPIClient.prototype.makeAPICall = function makeAPICall(endpoint, optData, optCb) {
+BaseAPIClient.prototype._makeAPICall = function _makeAPICall(endpoint, apiArgs, apiOptArgs, optCb) {
   var promise;
-  var args;
   var _this = this;
-  var apiCallArgs = helpers.getAPICallArgs(this._token, optData, optCb);
-
-  args = {
+  var args = {
     url: urlJoin(this.slackAPIUrl, endpoint),
-    data: apiCallArgs.data,
+    data: helpers.getApiCallData(this._token, apiArgs, apiOptArgs),
     headers: {
       'User-Agent': this.userAgent
     }
   };
 
-  if (!apiCallArgs.cb) {
+  if (!optCb) {
     promise = new Promise(function makeAPICallPromiseResolver(resolve, reject) {
       _this.requestQueue.push({
         args: args,
@@ -171,7 +170,7 @@ BaseAPIClient.prototype.makeAPICall = function makeAPICall(endpoint, optData, op
   } else {
     this.requestQueue.push({
       args: args,
-      cb: apiCallArgs.cb
+      cb: optCb
     });
   }
 

lib/clients/helpers.js

@@ -2,37 +2,49 @@
  * Helpers for working with Slack API clients.
  */
 
-var assign = require('lodash').assign;
-var isFunction = require('lodash').isFunction;
+// For some reason eslint sees the target[key] assigns as an issue
+/* eslint no-param-reassign: 0 */
+
 var isUndefined = require('lodash').isUndefined;
+var isPlainObject = require('lodash').isPlainObject;
 var isString = require('lodash').isString;
 var forEach = require('lodash').forEach;
 
 
-/**
- *
- * @param {object} data
- * @returns {object}
- */
-var getData = function getData(data, token) {
-  var newData = {};
-  assign(data, data ? data.opts || {} : {});
+var assignApiArgs = function assignApiArgs(target, source) {
+  if (!isPlainObject(source)) {
+    return;
+  }
 
-  forEach(data || {}, function getValidData(val, key) {
+  forEach(source, function getValidData(val, key) {
     if (!isUndefined(val) && val !== null && key !== 'opts') {
       // For the web API, this should always be a JSON-encoded array, see:
       //   https://api.slack.com/docs/attachments
       if (key === 'attachments') {
         if (isString(val)) {
-          newData[key] = val;
+          target[key] = val;
         } else {
-          newData[key] = JSON.stringify(val);
+          target[key] = JSON.stringify(val);
         }
       } else if (key !== 'opts') {
-        newData[key] = val;
+        target[key] = val;
       }
     }
   });
+};
+
+
+/**
+ *
+ * @param token
+ * @param requiredArgs
+ * @param optArgs
+ * @returns {{}}
+ */
+var getApiCallData = function getApiCallData(token, requiredArgs, optArgs) {
+  var newData = {};
+  assignApiArgs(newData, optArgs);
+  assignApiArgs(newData, requiredArgs);
 
   // There are a couple of API calls that don't require tokens, so check before passing it through
   if (token) {
@@ -43,30 +55,4 @@ var getData = function getData(data, token) {
 };
 
 
-var getAPICallArgs = function getAPICallArgs(token, optData, optCb) {
-  var data;
-  var cb;
-
-  if (arguments.length === 1) {
-    data = getData({}, token);
-  } else if (arguments.length === 2) {
-    if (isFunction(arguments[1])) {
-      cb = arguments[1];
-      data = getData({}, token);
-    } else {
-      data = getData(optData, token);
-    }
-  } else if (arguments.length === 3) {
-    cb = optCb;
-    data = getData(optData, token);
-  }
-
-  return {
-    cb: cb,
-    data: data
-  };
-};
-
-
-module.exports.getData = getData;
-module.exports.getAPICallArgs = getAPICallArgs;
+module.exports.getApiCallData = getApiCallData;

lib/clients/rtm/client.js

@@ -197,7 +197,7 @@ RTMClient.prototype._createFacets = function _createFacets() {
    * @type {RtmFacet}
    * @private
    */
-  this._rtm = new RtmFacet(bind(this.makeAPICall, this));
+  this._rtm = new RtmFacet(bind(this._makeAPICall, this));
 };
 
 

lib/clients/web/client.js

@@ -34,7 +34,7 @@ WebAPIClient.prototype._createFacets = function _createFacets() {
 
   WebAPIClient.super_.prototype._createFacets.call(this);
 
-  makeAPICall = bind(this.makeAPICall, this);
+  makeAPICall = bind(this._makeAPICall, this);
   forEach(facets, function registerWebClientFacet(Facet) {
     newFacet = new Facet(makeAPICall);
     this[newFacet.name] = newFacet;

lib/clients/web/facets/api.js

@@ -18,16 +18,12 @@ function ApiFacet(makeAPICall) {
  * @see {@link https://api.slack.com/methods/api.test|api.test}
  *
  * @param {Object=} opts
- * @param {?} opts.error Error response to return
- * @param {?} opts.foo example property to return
- * @param {function} optCb Optional callback, if not using promises.
+ * @param {?} opts.error - Error response to return
+ * @param {?} opts.foo - example property to return
+ * @param {function=} optCb Optional callback, if not using promises.
  */
 ApiFacet.prototype.test = function test(opts, optCb) {
-  var args = {
-    opts: opts
-  };
-
-  return this.makeAPICall('api.test', args, optCb);
+  return this.makeAPICall('api.test', null, opts, optCb);
 };
 
 

lib/clients/web/facets/auth.js

@@ -17,12 +17,10 @@ function AuthFacet(makeAPICall) {
  * Checks authentication & identity.
  * @see {@link https://api.slack.com/methods/auth.test|auth.test}
  *
- * @param {function} optCb Optional callback, if not using promises.
+ * @param {function=} optCb Optional callback, if not using promises.
  */
 AuthFacet.prototype.test = function test(optCb) {
-  var args = {};
-
-  return this.makeAPICall('auth.test', args, optCb);
+  return this.makeAPICall('auth.test', null, null, optCb);
 };