asana 1.0.2 → 2.0.0

package/lib/client.js

@@ -1,250 +0,0 @@
-var Dispatcher = require('./dispatcher');
-var resources = require('./resources');
-var BasicAuthenticator = require('./auth/basic_authenticator');
-var OauthAuthenticator = require('./auth/oauth_authenticator');
-var App = require('./auth/app');
-var autoDetect = require('./auth/auto_detect');
-
-/**
- * Constructs a Client with instances of all the resources using the dispatcher.
- * It also keeps a reference to the dispatcher so that way the end user can have
- * access to it.
- * @class
- * @classdesc A wrapper for the Asana API which is authenticated for one user
- * @param {Dispatcher} dispatcher The request dispatcher to use
- * @param {Object} options        Options to configure the client
- * @param {String} [clientId]     ID of the client, required for Oauth
- * @param {String} [clientSecret] Secret key, for some Oauth flows
- * @param {String} [redirectUri]  Default redirect URI for this client
- * @param {String} [asanaBaseUrl] Base URL for Asana, for debugging
- */
-function Client(dispatcher, options) {
-  options = options || {};
-  /**
-   * The internal dispatcher. This is mostly used by the resources but provided
-   * for custom requests to the API or API features that have not yet been added
-   * to the client.
-   * @type {Dispatcher}
-   */
-  this.dispatcher = dispatcher;
-  /**
-   * An instance of the Attachments resource.
-   * @type {Attachments}
-   */
-  this.attachments = new resources.Attachments(this.dispatcher);
-  /**
-   * An instance of the AuditLogAPI resource.
-   * @type {AuditLogAPI}
-   */
-  this.auditLogAPI = new resources.AuditLogAPI(this.dispatcher);
-  /**
-   * An instance of the BatchAPI resource.
-   * @type {BatchAPI}
-   */
-  this.batchAPI = new resources.BatchAPI(this.dispatcher);
-  /**
-   * An instance of the CustomFieldSettings resource.
-   * @type {CustomFieldSettings}
-   */
-  this.customFieldSettings = new resources.CustomFieldSettings(this.dispatcher);
-  /**
-   * An instance of the CustomFields resource.
-   * @type {CustomFields}
-   */
-  this.customFields = new resources.CustomFields(this.dispatcher);
-  /**
-   * An instance of the Events resource.
-   * @type {Events}
-   */
-  this.events = new resources.Events(this.dispatcher);
-  /**
-   * An instance of the Jobs resource.
-   * @type {Jobs}
-   */
-  this.jobs = new resources.Jobs(this.dispatcher);
-  /**
-   * An instance of the OrganizationExports resource.
-   * @type {Events}
-   */
-  this.organizationExports = new resources.OrganizationExports(this.dispatcher);
-  /**
-   * An instance of the Portfolios resource.
-   * @type {Portfolios}
-   */
-  this.portfolios = new resources.Portfolios(this.dispatcher);
-  /**
-   * An instance of the PortfolioMemberships resource.
-   * @type {PortfolioMemberships}
-   */
-  this.portfolioMemberships =
-      new resources.PortfolioMemberships(this.dispatcher);
-  /**
-   * An instance of the Projects resource.
-   * @type {Projects}
-   */
-  this.projects = new resources.Projects(this.dispatcher);
-  /**
-   * An instance of the ProjectMemberships resource.
-   * @type {ProjectMemberships}
-   */
-  this.projectMemberships = new resources.ProjectMemberships(this.dispatcher);
-  /**
-   * An instance of the ProjectStatuses resource.
-   * @type {ProjectStatuses}
-   */
-  this.projectStatuses = new resources.ProjectStatuses(this.dispatcher);
-  /**
-   * An instance of the Sections resource.
-   * @type {Sections}
-   */
-  this.sections = new resources.Sections(this.dispatcher);
-  /**
-   * An instance of the Stories resource.
-   * @type {Stories}
-   */
-  this.stories = new resources.Stories(this.dispatcher);
-  /**
-   * An instance of the Tags resource.
-   * @type {Tags}
-   */
-  this.tags = new resources.Tags(this.dispatcher);
-  /**
-   * An instance of the Tasks resource.
-   * @type {Tasks}
-   */
-  this.tasks = new resources.Tasks(this.dispatcher);
-  /**
-   * An instance of the Teams resource.
-   * @type {Teams}
-   */
-  this.teams = new resources.Teams(this.dispatcher);
-  /**
-   * An instance of the Typeahead resource.
-   * @type {Teams}
-   */
-  this.typeahead = new resources.Typeahead(this.dispatcher);
-  /**
-   * An instance of the Users resource.
-   * @type {Users}
-   */
-  this.users = new resources.Users(this.dispatcher);
-  /**
-   * An instance of the UserTaskLists resource.
-   * @type {UserTaskLists}
-   */
-  this.userTaskLists = new resources.UserTaskLists(this.dispatcher);
-  /**
-   * An instance of the Workspaces resource.
-   * @type {Workspaces}
-   */
-  this.workspaces = new resources.Workspaces(this.dispatcher);
-  /**
-   * An instance of the WorkspaceMemberships resource.
-   * @type {Workspaces}
-   */
-  this.workspaceMemberships =
-      new resources.WorkspaceMemberships(this.dispatcher);
-  /**
-   * An instance of the Webhooks resource.
-   * @type {Webhooks}
-   */
-  this.webhooks = new resources.Webhooks(this.dispatcher);
-
-  // Store off Oauth info.
-  this.app = new App(options);
-}
-
-/**
- * Ensures the client is authorized to make requests. Kicks off the
- * configured Oauth flow, if any.
- *
- * @returns {Promise<Client>} A promise that resolves to this client when
- *     authorization is complete.
- */
-Client.prototype.authorize = function() {
-  var me = this;
-  return me.dispatcher.authorize().then(function() {
-    return me;
-  });
-};
-
-/**
- * DEPRECATED: this only exists for backwards compatibility and
- * will be removed in a future version of the client library.
- * Configure the Client to use a user's PAT and then authenticate
- * through HTTP Basic Authentication.
- * @param  {String} accessToken The Asana PAT of the user
- * @return {Client}        this
- */
-Client.prototype.useBasicAuth = function(accessToken) {
-  this.dispatcher.setAuthenticator(new BasicAuthenticator(accessToken));
-  return this;
-};
-
-/**
- * Configure the client to authenticate using a Personal Access Token.
- * @param  {String} accessToken The Personal Access Token to use for
- * authenticating requests.
- * @return {Client}             this
- */
-Client.prototype.useAccessToken = function(accessToken) {
-    var authenticator = new OauthAuthenticator({
-        credentials: accessToken
-    });
-
-    this.dispatcher.setAuthenticator(authenticator);
-    return this;
-};
-
-/**
- * Configure the client to authenticate via Oauth. Credentials can be
- * supplied, or they can be obtained by running an Oauth flow.
- * @param  {Object} options Options for Oauth. Includes any options for
- *     the selected flow.
- * @option {Function} [flowType]  Type of OauthFlow to use to obtain user
- *     authorization. Defaults to autodetect based on environment.
- * @option {Object} [credentials] Credentials to use; no flow required to
- *     obtain authorization. This object should at a minimum contain an
- *     `access_token` string field.
- * @option {Function} [refreshCredentialsCallback] An optional callback
- *    function to execute once the authenticator auto refreshes
- *    access credentials.
- *    For Example:
- *    function(credentials){
- *     console.log("Your new credentials are:"+credentials)
- *    }
- * @return {Client}       this
- */
-Client.prototype.useOauth = function(options) {
-  options = options || {};
-  options.app = this.app;
-
-  var FlowType = options.flowType || autoDetect();
-  // If there are no credentials, then we can't proceed without a flow.
-  if (!options.credentials && FlowType === null) {
-    throw new Error('Could not autodetect Oauth flow type');
-  }
-  var flow = new FlowType(options);
-  var authenticator = new OauthAuthenticator({
-    app: this.app,
-    credentials: options.credentials,
-    flow: flow,
-    refreshCredentialsCallback: options.refreshCredentialsCallback || null
-  });
-
-  this.dispatcher.setAuthenticator(authenticator);
-  return this;
-};
-
-/**
- * Creates a new client.
- * @param {Object} options Options for specifying the client, see constructor.
- */
-Client.create = function(options) {
-  options = options || {};
-  return new Client(
-      new Dispatcher(options),
-      options);
-};
-
-module.exports = Client;

package/lib/default_environment.js

@@ -1,21 +0,0 @@
-/* jshint browser: true */
-/* global chrome */
-
-function defaultEnvironment() {
-  var env = {};
-  if (typeof(window) !== 'undefined') {
-    // Browser
-    env.window = window;
-  }
-  if (typeof(chrome) !== 'undefined') {
-    // Chrome Extension
-    env.chrome = chrome;
-  }
-  if (typeof(process) !== 'undefined') {
-    // NodeJS script
-    env.process = process;
-  }
-  return env;
-}
-
-module.exports = defaultEnvironment;

package/lib/dispatcher.js

@@ -1,438 +0,0 @@
-var errors = require('./errors');
-var Bluebird = require('bluebird');
-var request = require('request');
-var _ = require('lodash');
-var querystring = require('querystring');
-
-var VERSION = require('../package.json').version;
-
-var STATUS_MAP = Object.keys(errors).reduce(function(map, key) {
-  var error = new errors[key](null);
-  if (error.status) {
-    map[error.status] = errors[key];
-  }
-  return map;
-}, {});
-
-// TODO: Provide same set of options for each request as for configuration,
-// so the config at construction time is just the "defaults"
-
-/**
- * Creates a dispatcher which will act as a basic wrapper for making HTTP
- * requests to the API, and handle authentication.
- * @class
- * @classdesc A HTTP wrapper for the Asana API
- * @param {Object} options for default behavior of the Dispatcher
- * @option {Authenticator} [authenticator] Object to use for authentication.
- *     Can also be set later with `setAuthenticator`.
- * @option {String} [retryOnRateLimit] Automatically handle `RateLimitEnforced`
- *     errors by sleeping and retrying after the waiting period.
- * @option {Function} [handleUnauthorized] Automatically handle
- *     `NoAuthorization` with the callback. If the callback returns `true`
- *     (or a promise resolving to `true), will retry the request.
- * @option {String} [asanaBaseUrl] Base URL for Asana, for debugging
- * @option {Number} [requestTimeout] Timeout (in milliseconds) to wait for the
- *     request to finish.
- */
-function Dispatcher(options) {
-  options = options || {};
-  /**
-   * The object to use to handle authentication.
-   * @type {Authenticator}
-   */
-  this.authenticator = options.authenticator || null;
-  /**
-   * The base URL for Asana
-   * @type {String}
-   */
-  this.asanaBaseUrl = options.asanaBaseUrl || 'https://app.asana.com/';
-  /**
-   * Whether requests should be automatically retried if rate limited.
-   * @type {Boolean}
-   */
-  this.retryOnRateLimit = options.retryOnRateLimit || false;
-  /**
-   * What headers should be included by default in all requests, if any.
-   * Can be overridden by individual requests.
-   * @type {Object}
-   */
-  this.defaultHeaders = options.defaultHeaders || {};
-  /**
-   * Handler for unauthorized requests which may seek reauthorization.
-   * Default behavior is available if configured with an Oauth authenticator
-   * that has a refresh token, and will refresh the current access token.
-   * @type {Function}
-   */
-  this.handleUnauthorized = (options.handleUnauthorized !== undefined) ?
-      options.handleUnauthorized : Dispatcher.maybeReauthorize;
-  /**
-   * Version info gathered from the system, to send with the request.
-   * @type {Object}
-   */
-  this._cachedVersionInfo = null;
-
-  /**
-   * The amount of time in milliseconds to wait for a request to finish.
-   * @type {Number}
-   */
-  this.requestTimeout = options.requestTimeout || null;
-
-  /**
-   * What proxy should be used by default in all requests, if any.
-   * Can be overridden by individual requests.
-   * @type {String}
-   */
-  this.defaultProxy = options.defaultProxy || null;
-  /**
-   * Whether the dispatcher logs the AsanaChange header or not.
-   * @type {boolean}
-   */
-  this.logAsanaChangeWarnings = options.logAsanaChangeWarnings !== false;
-}
-
-/**
- * The relative API path for the current version of the Asana API.
- * @type {String}
- */
-Dispatcher.API_PATH = 'api/1.0';
-
-/**
- * Default handler for requests that are considered unauthorized.
- * Requests that the authenticator try to refresh its credentials if
- * possible.
- * @return {Promise<boolean>} True iff refresh was successful, false if not.
- */
-Dispatcher.maybeReauthorize = function() {
-  if (!this.authenticator) {
-    return false;
-  }
-  return this.authenticator.refreshCredentials();
-};
-
-/**
- * Whether the request library should show debug logs
- */
-Dispatcher.prototype.debug = function(flag) {
-  request.debug = flag;
-};
-
-/**
- * Creates an Asana API Url by concatenating the ROOT_URL with path provided.
- * @param  {String} path The path
- * @return {String}      The url
- */
-Dispatcher.prototype.url = function(path) {
-  return this.asanaBaseUrl + Dispatcher.API_PATH + path;
-};
-
-/**
- * Configure the authentication mechanism to use.
- * @returns {Dispatcher} this
- */
-Dispatcher.prototype.setAuthenticator = function(authenticator) {
-  this.authenticator = authenticator;
-  return this;
-};
-
-/**
- * Ensure the dispatcher is authorized to make requests. Call this before
- * making any API requests.
- *
- * @returns {Promise} Resolves when the dispatcher is authorized, rejected if
- *     there was a problem authorizing.
- */
-Dispatcher.prototype.authorize = function() {
-  if (this.authenticator === null) {
-    throw new Error('No authenticator configured for dispatcher');
-  }
-  return this.authenticator.establishCredentials();
-};
-
-/**
- * Logs the Asana-Change header if the request is affected and
- * has not Asana-Enabled the flag.
- * @param {Object} reqHeaders   headers in the request
- * @param {Object} resHeaders   headers in the response
- */
-Dispatcher.prototype.logAsanaChangeHeader = function(reqHeaders, resHeaders) {
-  var changeHeaderKey = null;
-
-  for (var key in resHeaders) {
-    if (key.toLowerCase() === 'asana-change') {
-      changeHeaderKey = key;
-    }
-  }
-
-  if (changeHeaderKey !== null) {
-    var accountedForFlags = [];
-
-    var addFlag = function(flag) {
-      accountedForFlags.push(flag.trim());
-    };
-
-    // Grab the request's asana-enable flags
-    for (var reqHeader in reqHeaders) {
-      if (!reqHeaders.hasOwnProperty(reqHeader)) {
-        continue;
-      }
-
-      if (reqHeader.toLowerCase() === 'asana-enable') {
-        reqHeaders[reqHeader].split(',').forEach(addFlag);
-      } else if (reqHeader.toLowerCase() === 'asana-disable') {
-        reqHeaders[reqHeader].split(',').forEach(addFlag);
-      }
-    }
-
-    var changes = resHeaders[changeHeaderKey].split(',');
-    changes.forEach(function(unsplitChange) {
-      var change = unsplitChange.split(';');
-
-      var name = null;
-      var info = null;
-      var affected = null;
-
-      for (var j = 0; j < change.length; j++) {
-        var field = change[j].split('=');
-
-        field[0] = field[0].trim();
-        if (field[0].trim() === 'name') {
-          name = field[1].trim();
-        }
-        else if (field[0].trim() === 'info') {
-          info = field[1].trim();
-        }
-        else if (field[0].trim() === 'affected') {
-          affected = field[1].trim();
-        }
-      }
-
-      // Only show the error if the flag was not in the request's
-      // asana-enable header
-      if (accountedForFlags.indexOf(name) === -1 && affected === 'true') {
-        var message = 'This request is affected by the "' + name +
-            '" deprecation. Please visit this url for more info: ' + info +
-            '\n' + 'Adding "' + name + '" to your "Asana-Enable" or ' +
-            '"Asana-Disable" header will opt in/out to this deprecation ' +
-            'and suppress this warning.';
-
-        console.error(message);
-      }
-    });
-  }
-};
-
-/**
- * Dispatches a request to the Asana API. The request parameters are passed to
- * the request module.
- * @param  {Object}  params The params for request
- * @param  {Object}  [dispatchOptions] Options for handling request/response
- * @return {Promise}        The response for the request
- */
-Dispatcher.prototype.dispatch = function(params, dispatchOptions) {
-  var me = this;
-  // TODO: actually honor these options as overriding defaults
-  dispatchOptions = dispatchOptions || {};
-
-  if (this.requestTimeout) {
-    params.timeout = this.requestTimeout;
-  }
-
-  if (this.defaultProxy) {
-    params.proxy = this.defaultProxy;
-  }
-
-  return new Bluebird(function(resolve, reject) {
-    function doRequest() {
-      if (me.authenticator !== null) {
-        me.authenticator.authenticateRequest(params);
-      }
-      params.headers = _.extend(
-          {}, params.headers, me.defaultHeaders, dispatchOptions.headers || {});
-      me._addVersionInfo(params);
-      request(params, function(err, res, payload) {
-        if (err) {
-          return reject(err);
-        }
-
-        // Handle Asana-Change header logging
-        if (me.logAsanaChangeWarnings) {
-          me.logAsanaChangeHeader(params.headers, res.headers);
-        }
-
-        if (STATUS_MAP[res.statusCode]) {
-          var error = new STATUS_MAP[res.statusCode](payload, res);
-
-          if (me.retryOnRateLimit &&
-              error instanceof (errors.RateLimitEnforced)) {
-            // Maybe attempt retry for rate limiting.
-            // Delay a half-second more in case of rounding error.
-            // TODO: verify Asana is always being conservative with duration
-            setTimeout(doRequest, error.retryAfterSeconds * 1000 + 500);
-
-          } else if (me.handleUnauthorized &&
-              error instanceof (errors.NoAuthorization)) {
-            // Maybe attempt to retry unauthorized requests after getting
-            // a new access token.
-            Bluebird.resolve(me.handleUnauthorized()).then(function(reauth) {
-              if (reauth) {
-                doRequest();
-              } else {
-                reject(error);
-              }
-            })
-            .catch(function() {
-                reject(error);
-            });
-          } else {
-            // Not an error we can handle.
-            return reject(error);
-          }
-        } else {
-          return resolve(payload);
-        }
-      });
-    }
-    doRequest();
-  });
-};
-
-/**
- * Dispatches a GET request to the Asana API.
- * @param  {String}  path    The path of the API
- * @param  {Object}  [query] The query params
- * @param  {Object}  [dispatchOptions] Options for handling the request and
- *     response. See `dispatch`.
- * @return {Promise}         The response for the request
- */
-Dispatcher.prototype.get = function(path, query, dispatchOptions) {
-  var params = {
-    method: 'GET',
-    url: this.url(path),
-    json: true
-  };
-  var options = this._parseApiOptions(query);
-  if (options) {
-    params.qs = options;
-  }
-
-  if (query) {
-    params.qs = Object.assign(query, params.qs);
-  }
-  return this.dispatch(params, dispatchOptions);
-};
-
-/**
- * Dispatches a POST request to the Asana API.
- * @param  {String} path The path of the API
- * @param  {Object} data The data to be sent
- * @param  {Object}  [dispatchOptions] Options for handling the request and
- *     response. See `dispatch`.
- * @return {Promise}     The response for the request
- */
-Dispatcher.prototype.post = function(path, data, dispatchOptions) {
-  var params = {
-    method: 'POST',
-    url: this.url(path),
-    json: {
-      data: data
-    }
-  };
-  var options = this._parseApiOptions(data);
-  if (options) {
-    params.qs = options;
-  }
-
-  return this.dispatch(params, dispatchOptions);
-};
-
-/**
- * Dispatches a PUT request to the Asana API.
- * @param  {String} path The path of the API
- * @param  {Object} data The data to be sent
- * @param  {Object}  [dispatchOptions] Options for handling the request and
- *     response. See `dispatch`.
- * @return {Promise}     The response for the request
- */
-Dispatcher.prototype.put = function(path, data, dispatchOptions) {
-  var params = {
-    method: 'PUT',
-    url: this.url(path),
-    json: {
-      data: data
-    }
-  };
-  var options = this._parseApiOptions(data);
-  if (options) {
-    params.qs = options;
-  }
-
-  return this.dispatch(params, dispatchOptions);
-};
-
-/**
- * Dispatches a DELETE request to the Asana API.
- * @param  {String} path The path of the API
- * @param  {Object}  [dispatchOptions] Options for handling the request and
- *     response. See `dispatch`.
- * @return {Promise}     The response for the request
- */
-Dispatcher.prototype.delete = function(path, dispatchOptions) {
-  var params = {
-    method: 'DELETE',
-    url: this.url(path)
-  };
-
-  return this.dispatch(params, dispatchOptions);
-};
-
-/**
- * @param request {Object} Request to add version header to.
- * @private
- */
-Dispatcher.prototype._addVersionInfo = function(request) {
-  if (!this._cachedVersionInfo) {
-    this._cachedVersionInfo = this._generateVersionInfo();
-  }
-  request.headers = request.headers || {};
-  request.headers['X-Asana-Client-Lib'] =
-      querystring.stringify(this._cachedVersionInfo);
-};
-
-/**
- * @return {Object} Dictionary of key-value pairs indicating library version
- * @private
- */
-Dispatcher.prototype._generateVersionInfo = function() {
-  if (typeof(navigator) === 'undefined' || typeof(window) === 'undefined') {
-    return {
-      'version': VERSION,
-      'language': 'NodeJS',
-      'language_version': process.version,
-      'os': process.platform
-    };
-  } else {
-    return {
-      'version': VERSION,
-      'language': 'BrowserJS'
-    };
-  }
-};
-
-Dispatcher.prototype._parseApiOptions = function(params) {
-  if (!params) {
-    return null;
-  }
-
-  var optionKeys = ['pretty', 'fields', 'expand'];
-  var options = {};
-
-  for (var i = 0; i < optionKeys.length; i++) {
-    if (params.hasOwnProperty(optionKeys[i])) {
-      options['opt_' + optionKeys[i]] = params[optionKeys[i]];
-    }
-  }
-
-  return options;
-};
-
-module.exports = Dispatcher;