docusign/components/admin.js

A DocuSign API helper library with promise support

// Handles administration of given organization's DocuSign account

var dsUtils = require('./../dsUtils');

exports.init = function (accountId, baseUrl, accessToken) {
  return {
    /**
     * Gets the account info for the given org accountId
     *
     * @memberOf Admin
     * @public
     * @function
     * @param {function} [callback] - Returned in the form of function(error, response).
     * @returns {Promise} - A thenable bluebird Promise; if callback is given it is called before the promise is resolved
     */

    getOrgAccountInfo: function (callback) {
      return getOrgAccountInfo(accountId, accessToken).asCallback(callback);
    },

    /**
     * Returns a list of users for the organization in the base URL
     *
     * @memberOf Admin
     * @public
     * @function
     * @param {function} [callback] - Returned in the form of function(error, users).
     * @returns {Promise} - A thenable bluebird Promise; if callback is given it is called before the promise is resolved
     */

    getUserList: function (callback) {
      return getUserList(accessToken, baseUrl).asCallback(callback);
    },

    /**
     * Creates a set of new users in DocuSign for the Org associated to the base URL
     *
     * @memberOf Admin
     * @public
     * @function
     * @param {object[]} usersToAdd - Array of Objects with account creation information.
     *   @param {string} usersToAdd[].first - First Name
     *   @param {string} usersToAdd[].last - Last Name
     *   @param {string} usersToAdd[].email - Email Address
     *   @param {string} usersToAdd[].password - Password
     *   @param {object} usersToAdd[].forgottenPasswordInfo - Hash of question and answers
     *     that will be asked when a password is forgotten. At least 1st pair is required
     *     @param {string} forgottenPasswordInfo.forgottenPasswordQuestion1
     *     @param {string} forgottenPasswordInfo.forgottenPasswordAnswer1
     *     @param {string} forgottenPasswordInfo.forgottenPasswordQuestion2
     *     @param {string} forgottenPasswordInfo.forgottenPasswordAnswer2
     *     @param {string} forgottenPasswordInfo.forgottenPasswordQuestion3
     *     @param {string} forgottenPasswordInfo.forgottenPasswordAnswer3
     *     @param {string} forgottenPasswordInfo.forgottenPasswordQuestion4
     *     @param {string} forgottenPasswordInfo.forgottenPasswordAnswer4
     * @param {function} [callback] - Returned in the form of function(error, response).
     * @returns {Promise} - A thenable bluebird Promise; if callback is given it is called before the promise is resolved
     */

    addUsers: function (usersToAdd, callback) {
      return addUsers(accessToken, baseUrl, usersToAdd).asCallback(callback);
    },

    /**
     * Deletes a set of users from DocuSign
     *
     * @memberOf Admin
     * @public
     * @function
     * @param {array} usersToDelete - Collection of users in the form of {userId: userId}
     * @param {function} [callback] - Returned in the form of function(error, response).
     * @returns {Promise} - A thenable bluebird Promise; if callback is given it is called before the promise is resolved
     */

    deleteUsers: function (usersToDelete, callback) {
      return deleteUsers(accessToken, baseUrl, usersToDelete).asCallback(callback);
    },

    /**
     * Gets the templates for a given account
     *
     * @memberOf Admin
     * @public
     * @function
     * @param {function} [callback] - Returned in the form of function(error, response).
     * @returns {Promise} - A thenable bluebird Promise; if callback is given it is called before the promise is resolved
     */

    getTemplates: function (callback) {
      return getTemplates(accessToken, baseUrl).asCallback(callback);
    },

    /**
     * Get the billing plan info for DS account with the given `apiToken`.
     *
     * Adds custom properties to plan object before sending it to the callback
     * envelopesLeft - calculated
     * name - shortcut for planName which is redundant plan.planName. :)
     *
     *
     * @memberOf Admin
     * @public
     * @function
     * @param {function} [callback] - Returned in the form of function(error, plan).
     * @returns {Promise} - A thenable bluebird Promise; if callback is given it is called before the promise is resolved
     */

    getPlan: function (callback) {
      return getPlan(accessToken, baseUrl).asCallback(callback);
    }
  };
};

/**
 * Gets the account info for the given org accountId
 *
 * @memberOf Admin
 * @private
 * @function
 * @param {string} accountId - DocuSign AccountId.
 * @param {string} apiToken - DocuSign API OAuth2 access token.
 * @returns {Promise} - A thenable bluebird Promise fulfilled with organization account info
 */
function getOrgAccountInfo (accountId, apiToken) {
  var options = {
    method: 'GET',
    url: dsUtils.getApiUrl() + '/accounts/' + accountId,
    headers: dsUtils.getHeaders(apiToken)
  };

  return dsUtils.makeRequest('Get DS Org Account Info', options);
}

/**
 * Returns a list of users for the organization in the base URL
 *
 * @memberOf Admin
 * @private
 * @function
 * @param {string} apiToken - DocuSign API OAuth2 access token.
 * @param {string} baseUrl - DocuSign API base URL.
 * @returns {Promise} - A thenable bluebird Promise fulfilled with user objects.
 */
function getUserList (apiToken, baseUrl, callback) {
  var options = {
    method: 'GET',
    url: baseUrl + '/users?additional_info=true',
    headers: dsUtils.getHeaders(apiToken, baseUrl)
  };

  return dsUtils.makeRequest('Get DS Account User List', options).then(function (response) {
    return response.users;
  });
}

/**
 * Creates a set of new users in DocuSign for the Org associated to the base URL
 *
 * @memberOf Admin
 * @private
 * @function
 * @param {string} apiToken - DocuSign API OAuth2 access token.
 * @param {string} baseUrl - DocuSign API base URL.
 * @param {object[]} usersToAdd - Array of Objects with account creation information.
 *   @param {string} usersToAdd[].first - First Name
 *   @param {string} usersToAdd[].last - Last Name
 *   @param {string} usersToAdd[].email - Email Address
 *   @param {string} usersToAdd[].password - Password
 *   @param {object} usersToAdd[].forgottenPasswordInfo - Hash of question and answers
 *     that will be asked when a password is forgotten. At least 1st pair is required
 *     @param {string} forgottenPasswordInfo.forgottenPasswordQuestion1
 *     @param {string} forgottenPasswordInfo.forgottenPasswordAnswer1
 *     @param {string} forgottenPasswordInfo.forgottenPasswordQuestion2
 *     @param {string} forgottenPasswordInfo.forgottenPasswordAnswer2
 *     @param {string} forgottenPasswordInfo.forgottenPasswordQuestion3
 *     @param {string} forgottenPasswordInfo.forgottenPasswordAnswer3
 *     @param {string} forgottenPasswordInfo.forgottenPasswordQuestion4
 *     @param {string} forgottenPasswordInfo.forgottenPasswordAnswer4
 * @returns {Promise} - A thenable bluebird Promise
 */
function addUsers (apiToken, baseUrl, usersToAdd) {
  var users = usersToAdd.map(function (user) {
    return {
      userName: user.first + ' ' + user.last,
      firstName: user.first,
      lastName: user.last,
      email: user.email,
      password: user.password,
      forgottenPasswordInfo: user.forgottenPasswordInfo,
      userSettings: [
        { name: 'canSendEnvelope', value: true }
      ]
    };
  });

  var options = {
    method: 'POST',
    url: baseUrl + '/users',
    headers: dsUtils.getHeaders(apiToken, baseUrl),
    json: {
      newUsers: users
    }
  };

  return dsUtils.makeRequest('Add Users to DS Account', options);
}

/**
 * Deletes a set of users from DocuSign
 *
 * @memberOf Admin
 * @private
 * @function
 * @param {string} apiToken - DS API OAuth2 access token.
 * @param {string} baseUrl - DS API base URL.
 * @param {array} usersToDelete - Collection of users in the form of {userId: userId}
 * @returns {Promise} - A thenable bluebird Promise
 */
function deleteUsers (apiToken, baseUrl, usersToDelete) {
  var userIds = usersToDelete.map(function (user) {
    return {
      userId: user.userId
    };
  });

  var options = {
    method: 'DELETE',
    url: baseUrl + '/users',
    headers: dsUtils.getHeaders(apiToken, baseUrl),
    json: {
      users: userIds
    }
  };

  return dsUtils.makeRequest('Delete Users in DS Account', options);
}

/**
 * Gets the templates for a given account
 *
 * @memberOf Admin
 * @private
 * @function
 * @param {string} apiToken - DocuSign API OAuth2 access token.
 * @param {string} baseUrl - DocuSign API base URL.
 * @returns {Promise} - A thenable bluebird Promise fulfilled with list of templates
 */
function getTemplates (apiToken, baseUrl) {
  var options = {
    method: 'GET',
    url: baseUrl + '/templates',
    headers: dsUtils.getHeaders(apiToken)
  };

  return dsUtils.makeRequest('Get Templates', options);
}

/**
 * Get the billing plan info for DS account with the given `apiToken`.
 *
 * Adds custom properties to plan object before sending it to the callback
 * envelopesLeft - calculated
 * name - shortcut for planName which is redundant plan.planName. :)
 *
 *
 * @memberOf Admin
 * @private
 * @function
 * @param {string} apiToken - DocuSign API OAuth2 access token.
 * @param {string} baseUrl - DocuSign API base URL.
 * @returns {Promise} - A thenable bluebird Promise fulfilled with the account plan.
 */
function getPlan (apiToken, baseUrl) {
  var options = {
    method: 'GET',
    url: baseUrl,
    headers: dsUtils.getHeaders(apiToken)
  };

  return dsUtils.makeRequest('Get Billing Plan Info', options).then(function (plan) {
    var envelopesLeft = plan.billingPeriodEnvelopesAllowed - plan.billingPeriodEnvelopesSent;

    // a negative number signifies unlimited amount
    plan.envelopesLeft = isNaN(envelopesLeft) ? -1 : /* istanbul ignore next */ envelopesLeft;

    plan.name = plan.planName;

    return plan;
  });
}