jsforce2 1.11.1

package/lib/oauth2.js

@@ -0,0 +1,206 @@
+/**
+ * @file Manages Salesforce OAuth2 operations
+ * @author Shinichi Tomita <shinichi.tomita@gmail.com>
+ */
+
+'use strict';
+
+var querystring = require('querystring'),
+    _ = require('lodash/core'),
+    Transport = require('./transport');
+
+var defaults = {
+  loginUrl : "https://login.salesforce.com"
+};
+
+/**
+ * OAuth2 class
+ *
+ * @class
+ * @constructor
+ * @param {Object} options - OAuth2 config options
+ * @param {String} [options.loginUrl] - Salesforce login server URL
+ * @param {String} [options.authzServiceUrl] - OAuth2 authorization service URL. If not specified, it generates from default by adding to login server URL.
+ * @param {String} [options.tokenServiceUrl] - OAuth2 token service URL. If not specified it generates from default by adding to login server URL.
+ * @param {String} options.clientId - OAuth2 client ID.
+ * @param {String} [options.clientSecret] - OAuth2 client secret (This is optional for public client).
+ * @param {String} options.redirectUri - URI to be callbacked from Salesforce OAuth2 authorization service.
+ */
+var OAuth2 = module.exports = function(options) {
+  if (options.authzServiceUrl && options.tokenServiceUrl) {
+    this.loginUrl = options.authzServiceUrl.split('/').slice(0, 3).join('/');
+    this.authzServiceUrl = options.authzServiceUrl;
+    this.tokenServiceUrl = options.tokenServiceUrl;
+    this.revokeServiceUrl = options.revokeServiceUrl;
+  } else {
+    this.loginUrl = options.loginUrl || defaults.loginUrl;
+    this.authzServiceUrl = this.loginUrl + "/services/oauth2/authorize";
+    this.tokenServiceUrl = this.loginUrl + "/services/oauth2/token";
+    this.revokeServiceUrl = this.loginUrl + "/services/oauth2/revoke";
+  }
+  this.clientId = options.clientId;
+  this.clientSecret = options.clientSecret;
+  this.redirectUri = options.redirectUri;
+  if (options.proxyUrl) {
+    this._transport = new Transport.ProxyTransport(options.proxyUrl);
+  } else if (options.httpProxy) {
+    this._transport = new Transport.HttpProxyTransport(options.httpProxy);
+  } else {
+    this._transport = new Transport();
+  }
+};
+
+
+
+/**
+ *
+ */
+_.extend(OAuth2.prototype, /** @lends OAuth2.prototype **/ {
+
+  /**
+   * Get Salesforce OAuth2 authorization page URL to redirect user agent.
+   *
+   * @param {Object} params - Parameters
+   * @param {String} [params.scope] - Scope values in space-separated string
+   * @param {String} [params.state] - State parameter
+   * @param {String} [params.code_challenge] - Code challenge value (RFC 7636 - Proof Key of Code Exchange)
+   * @returns {String} Authorization page URL
+   */
+  getAuthorizationUrl : function(params) {
+    params = _.extend({
+      response_type : "code",
+      client_id : this.clientId,
+      redirect_uri : this.redirectUri
+    }, params || {});
+    return this.authzServiceUrl +
+      (this.authzServiceUrl.indexOf('?') >= 0 ? "&" : "?") +
+      querystring.stringify(params);
+  },
+
+  /**
+   * @typedef TokenResponse
+   * @type {Object}
+   * @property {String} access_token
+   * @property {String} refresh_token
+   */
+
+  /**
+   * OAuth2 Refresh Token Flow
+   *
+   * @param {String} refreshToken - Refresh token
+   * @param {Callback.<TokenResponse>} [callback] - Callback function
+   * @returns {Promise.<TokenResponse>}
+   */
+  refreshToken : function(refreshToken, callback) {
+    var params = {
+      grant_type : "refresh_token",
+      refresh_token : refreshToken,
+      client_id : this.clientId
+    };
+    if (this.clientSecret) {
+      params.client_secret = this.clientSecret;
+    }
+    return this._postParams(params, callback);
+  },
+
+  /**
+   * OAuth2 Web Server Authentication Flow (Authorization Code)
+   * Access Token Request
+   *
+   * @param {String} code - Authorization code
+   * @param {Object} [params] - Optional parameters to send in token retrieval
+   * @param {String} [params.code_verifier] - Code verifier value (RFC 7636 - Proof Key of Code Exchange)
+   * @param {Callback.<TokenResponse>} [callback] - Callback function
+   * @returns {Promise.<TokenResponse>}
+   */
+  requestToken : function(code, params, callback) {
+    if (typeof params === 'function') {
+      callback = params;
+      params = {};
+    }
+    params = _.extend({
+      grant_type : "authorization_code",
+      code : code,
+      client_id : this.clientId,
+      redirect_uri : this.redirectUri
+    }, params || {});
+    if (this.clientSecret) {
+      params.client_secret = this.clientSecret;
+    }
+    return this._postParams(params, callback);
+  },
+
+  /**
+   * OAuth2 Username-Password Flow (Resource Owner Password Credentials)
+   *
+   * @param {String} username - Salesforce username
+   * @param {String} password - Salesforce password
+   * @param {Callback.<TokenResponse>} [callback] - Callback function
+   * @returns {Promise.<TokenResponse>}
+   */
+  authenticate : function(username, password, callback) {
+    return this._postParams({
+      grant_type : "password",
+      username : username,
+      password : password,
+      client_id : this.clientId,
+      client_secret : this.clientSecret,
+      redirect_uri : this.redirectUri
+    }, callback);
+  },
+
+  /**
+   * OAuth2 Revoke Session or API Token
+   *
+   * @param {String} token - Access or Refresh token to revoke. Passing in the Access token revokes the session. Passing in the Refresh token revokes API Access.
+   * @param {Callback.<undefined>} [callback] - Callback function
+   * @returns {Promise.<undefined>}
+   */
+  revokeToken : function(token, callback) {
+    return this._transport.httpRequest({
+      method : 'POST',
+      url : this.revokeServiceUrl,
+      body: querystring.stringify({ token: token }),
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      }
+    }).then(function(response) {
+      if (response.statusCode >= 400) {
+        var res = querystring.parse(response.body);
+        if (!res || !res.error) {
+          res = { error: "ERROR_HTTP_"+response.statusCode, error_description: response.body };
+        }
+        var err = new Error(res.error_description);
+        err.name = res.error;
+        throw err;
+      }
+    }).thenCall(callback);
+  },
+
+  /**
+   * @private
+   */
+  _postParams : function(params, callback) {
+    return this._transport.httpRequest({
+      method : 'POST',
+      url : this.tokenServiceUrl,
+      body : querystring.stringify(params),
+      headers : {
+        "content-type" : "application/x-www-form-urlencoded"
+      }
+    }).then(function(response) {
+      var res;
+      try {
+        res = JSON.parse(response.body);
+      } catch(e) {}
+      if (response.statusCode >= 400) {
+        res = res || { error: "ERROR_HTTP_"+response.statusCode, error_description: response.body };
+        var err = new Error(res.error_description);
+        err.name = res.error;
+        throw err;
+      }
+      return res;
+    }).thenCall(callback);
+  }
+
+});

package/lib/process.js

@@ -0,0 +1,275 @@
+/**
+ * @file Process class to manage/run workflow rule and approval process
+ * @author Shinichi Tomita <shinichi.tomita@gmail.com>
+ */
+
+'use strict';
+
+var _ = require('lodash/core'),
+    Promise = require('./promise'),
+    Conneciton = require('./connection');
+
+/**
+ * A class which manages process rules and approval processes
+ *
+ * @class
+ * @param {Connection} conn - Connection object
+ */
+var Process = module.exports = function(conn) {
+  /**
+   * Object which mangages process rules
+   * @member {Process~ProcessRule} Process#rule
+   */
+  this.rule = new ProcessRule(conn);
+  /**
+   * Object which mangages approval process
+   * @member {Process~ApprovalProcess} Process#approval
+   */
+  this.approval = new ApprovalProcess(conn);
+};
+
+/**
+ * A class which manages process (workflow) rules
+ *
+ * @class Process~ProcessRule
+ * @param {Connection} conn - Connection object
+ */
+var ProcessRule = function(conn) {
+  this._conn = conn;
+};
+
+/**
+ * @typedef {Object} Process~ProcessRuleDefinition
+ * @prop {String} id - Id of approval process definition
+ * @prop {String} name - Name of process rule definition
+ * @prop {String} object - SObject name which process rule is defined
+ */
+
+/**
+ * Get all process rule definitions registered to sobjects
+ *
+ * @method Process~ProcessRule#list
+ * @param {Callback.<Map.<String, Array.<Process~ProcessRuleDefinition>>>} [callback] - Callback function
+ * @returns {Promise.<Map.<String, Array.<Process~ProcessRuleDefinition>>>}
+ */
+ProcessRule.prototype.list = function(callback) {
+  return this._conn.request("/process/rules").then(function(res) {
+    return res.rules;
+  }).thenCall(callback);
+};
+
+
+/**
+ * @typedef {Object} Process~ProcessRuleTriggerResult
+ * @prop {Boolean} success - Is process rule trigger succeeded or not
+ * @prop {Array.<Object>} errors - Array of errors returned if the request failed
+ */
+
+/**
+ * Trigger process rule for given entities
+ *
+ * @method Process~ProcessRule#trigger
+ * @param {String|Array.<String>} contextIds - Entity ID(s) to trigger workflow process
+ * @param {Callback.<Process~ProcessRuleTriggerResult>} [callback] - Callback function
+ * @returns {Promise.<Process~ProcessRuleTriggerResult>}
+ */
+ProcessRule.prototype.trigger = function(contextIds, callback) {
+  contextIds = _.isArray(contextIds) ? contextIds : [ contextIds ];
+  return this._conn.request({
+    method: "POST",
+    url: "/process/rules/",
+    body: JSON.stringify({
+      contextIds: contextIds
+    }),
+    headers: {
+      "content-type": "application/json"
+    }
+  }).thenCall(callback);
+};
+
+/**
+ * A class which manages approval processes
+ *
+ * @class Process~ApprovalProcess
+ * @param {Connection} conn - Connection object
+ */
+var ApprovalProcess = function(conn) {
+  this._conn = conn;
+};
+
+/**
+ * @typedef {Object} Process~ApprovalProcessDefinition
+ * @prop {String} id - Id of approval process definition
+ * @prop {String} name - Name of approval process definition
+ * @prop {String} object - SObject name which approval process is defined
+ * @prop {Number} sortOrder - Processing order of approval in SObject
+ */
+/**
+ * Get all approval process definitions registered to sobjects
+ *
+ * @method Process~ApprovalProcess#list
+ * @param {Callback.<Map.<String, Array.<ApprovalProcessDefinition>>>} [callback] - Callback function
+ * @returns {Promise.<Map.<String, Array.<ApprovalProcessDefinition>>>}
+ */
+ApprovalProcess.prototype.list = function(callback) {
+  return this._conn.request("/process/approvals").then(function(res) {
+    return res.approvals;
+  }).thenCall(callback);
+};
+
+/**
+ * @typedef {Object} Process~ApprovalProcessRequestResult
+ * @prop {Boolean} success - True if processing or approval completed successfully
+ * @prop {Array.<Object>} errors - The set of errors returned if the request failed
+ * @prop {Array.<String>} actorIds - IDs of the users who are currently assigned to this approval step
+ * @prop {String} entityId - Object being processed
+ * @prop {String} instanceId - ID of the ProcessInstance associated with the object submitted for processing
+ * @prop {String} instanceStatus - Status of the current process instance (not an individual object but the entire process instance)
+ * @prop {Array.<String>} newWorkItemIds - Case-insensitive IDs that point to ProcessInstanceWorkitem items (the set of pending approval requests)
+ */
+
+/**
+ * Send bulk requests for approval process
+ *
+ * @method Process~ApprovalProcess#request
+ * @param {Array.<ApprovalProcessRequest>} requests - Array of approval process request to send
+ * @param {Callback.<Array.<ApprovalProcessRequestResult>>} - Callback function
+ * @param {Promise.<Array.<ApprovalProcessRequestResult>>}
+ */
+ApprovalProcess.prototype.request = function(requests, callback) {
+  requests = requests.map(function(req) {
+    return req._request ? req._request : req;
+  });
+  return this._conn.request({
+    method: 'POST',
+    url: '/process/approvals',
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ requests: requests })
+  }).thenCall(callback);
+};
+
+/**
+ * Create approval process request
+ *
+ * @private
+ */
+ApprovalProcess.prototype._createRequest = function(actionType, contextId, comments, options, callback) {
+  if (typeof comments === "function") {
+    callback = comments;
+    options = null;
+    comments = null;
+  }
+  if (typeof options === "function") {
+    callback = options;
+    options = null;
+  }
+  options = options || {};
+  var request = {
+    actionType: actionType,
+    contextId: contextId,
+    comments: comments
+  };
+  _.extend(request, options);
+  return new ApprovalProcessRequest(this, request).thenCall(callback);
+};
+
+/**
+ * Submit approval request for an item
+ *
+ * @method Process~ApprovalProcess#submit
+ * @param {String} contextId - ID of the item that is being acted upon
+ * @param {String} [comments] - Comment to add to the history step associated with this request
+ * @param {Object} [options] - Request parameters
+ * @param {Array.<String>} [options.nextApproverIds] - If the process requires specification of the next approval, the ID of the user to be assigned the next request
+ * @param {String} [options.processDefinitionNameOrId] - Developer name or ID of the process definition
+ * @param {Boolean} [options.skipEntryCriteria] - Determines whether to evaluate the entry criteria for the process (true) or not (false) if the process definition name or ID isn’t null
+ * @param {Callback.<ApprovalProcessRequestResult>} [callback] - Callback function
+ * @returns {ApprovalProcessRequest}
+ */
+ApprovalProcess.prototype.submit = function(contextId, comments, options, callback) {
+  return this._createRequest("Submit", contextId, comments, options, callback);
+};
+
+/**
+ * Approve approval request for an item
+ *
+ * @method Process~ApprovalProcess#approve
+ * @param {String} workitemId - ID of the item that is being acted upon
+ * @param {String} [comments] - Comment to add to the history step associated with this request
+ * @param {Object} [options] - Request parameters
+ * @param {Array.<String>} [options.nextApproverIds] - If the process requires specification of the next approval, the ID of the user to be assigned the next request
+ * @param {String} [options.processDefinitionNameOrId] - Developer name or ID of the process definition
+ * @param {Boolean} [options.skipEntryCriteria] - Determines whether to evaluate the entry criteria for the process (true) or not (false) if the process definition name or ID isn’t null
+ * @param {Callback.<ApprovalProcessRequestResult>} [callback] - Callback function
+ * @returns {ApprovalProcessRequest}
+ */
+ApprovalProcess.prototype.approve = function(workitemId, comments, options, callback) {
+  return this._createRequest("Approve", workitemId, comments, options, callback);
+};
+
+/**
+ * Reject approval request for an item
+ *
+ * @method Process~ApprovalProcess#reject
+ * @param {String} workitemId - ID of the item that is being acted upon
+ * @param {String} [comments] - Comment to add to the history step associated with this request
+ * @param {Object} [options] - Request parameters
+ * @param {Array.<String>} [options.nextApproverIds] - If the process requires specification of the next approval, the ID of the user to be assigned the next request
+ * @param {String} [options.processDefinitionNameOrId] - Developer name or ID of the process definition
+ * @param {Boolean} [options.skipEntryCriteria] - Determines whether to evaluate the entry criteria for the process (true) or not (false) if the process definition name or ID isn’t null
+ * @param {Callback.<ApprovalProcessRequestResult>} [callback] - Callback function
+ * @returns {ApprovalProcessRequest}
+ */
+ApprovalProcess.prototype.reject = function(workitemId, comments, options, callback) {
+  return this._createRequest("Reject", workitemId, comments, options, callback);
+};
+
+/**
+ * A class representing approval process request
+ *
+ * @protected
+ * @class Process~ApprovalProcessRequest
+ * @implements {Promise.<Process~ApprovalProcessRequestResult>}
+ * @param {Process~ApprovalProcess} process - ApprovalProcess
+ * @param {Object} request - Request parameters
+ * @param {String} request.actionType - Represents the kind of action to take: Submit, Approve, or Reject
+ * @param {String} request.contextId - ID of the item that is being acted upon
+ * @param {String} request.comments - Comment to add to the history step associated with this request
+ * @param {Array.<String>} [request.nextApproverIds] - If the process requires specification of the next approval, the ID of the user to be assigned the next request
+ * @param {String} [request.processDefinitionNameOrId] - Developer name or ID of the process definition
+ * @param {Boolean} [request.skipEntryCriteria] - Determines whether to evaluate the entry criteria for the process (true) or not (false) if the process definition name or ID isn’t null
+ */
+var ApprovalProcessRequest = function(process, request) {
+  this._process = process;
+  this._request = request;
+};
+
+/**
+ * Promise/A+ interface
+ * http://promises-aplus.github.io/promises-spec/
+ *
+ * @method Process~ApprovalProcessRequest#then
+ */
+ApprovalProcessRequest.prototype.then = function(onResolve, onReject) {
+  if (!this._promise) {
+    this._promise = this._process.request([ this ]).then(function(rets) {
+      return rets[0];
+    });
+  }
+  this._promise.then(onResolve, onReject);
+};
+
+/**
+ * Promise/A+ extension
+ * Call "then" using given node-style callback function
+ *
+ * @method Process~ApprovalProcessRequest#thenCall
+ */
+ApprovalProcessRequest.prototype.thenCall = function(callback) {
+  return callback ? this.then(function(res) {
+    callback(null, res);
+  }, function(err) {
+    callback(err);
+  }) :
+  this;
+};

package/lib/promise.js

@@ -0,0 +1,164 @@
+/*global process*/
+
+'use strict';
+
+var _ = require('lodash/core');
+
+/**
+ * @callback ResolvedCallback
+ * @param {T} result - Resolved value
+ * @returns {S}
+ * @template T,S
+ */
+
+/**
+ * @callback RejectedCallback
+ * @param {Error} reason - Rejected reason
+ * @returns {S}
+ * @template S
+ */
+
+/**
+ * @callback ResolveCallback
+ * @param {T} result
+ * @template T
+ */
+
+/**
+ * @callback RejectedCallback
+ * @param {Error} reason - Rejected reason
+ * @returns {S}
+ * @template S
+ */
+
+/**
+ * @callback PromiseCallback
+ * @param {ResolveCallback.<T>} resolve
+ * @param {RejectCallback} reject
+ * @template T
+ */
+
+/**
+ * Promise class with a little extension
+ *
+ * @class Promise
+ * @constructor
+ * @param {PromiseCallback.<T>}
+ * @template T
+ */
+var Promise = require('promise/lib/es6-extensions');
+
+/**
+ * The "then" method from the Promises/A+ specification
+ *
+ * @method Promise#then
+ * @param {FulfilledCallback.<T, S1>} [onFulfilled]
+ * @param {RejectedCallback.<S2>} [onRejected]
+ * @returns {Promise.<S1|S2>}
+ */
+
+/**
+ * Call "then" using given node-style callback function.
+ * This is basically same as "nodeify" except that it always return the original promise
+ *
+ * @method Promise#thenCall
+ * @param {Callback.<T>} [callback] - Callback function
+ * @returns {Promise}
+ */
+Promise.prototype.thenCall = function(callback) {
+  if (_.isFunction(callback)) {
+    this.then(function(res) {
+      process.nextTick(function() {
+        callback(null, res);
+      });
+    }, function(err) {
+      process.nextTick(function() {
+        callback(err);
+      });
+    });
+  }
+  return this;
+};
+
+/**
+ * A sugar method, equivalent to promise.then(undefined, onRejected).
+ *
+ * @method Promise#catch
+ * @param {RejectedCallback.<S>} onRejected
+ * @returns {Promise.<S>}
+ */
+
+/**
+ * Synonym of Promise#catch
+ *
+ * @method Promise#fail
+ * @param {RejectedCallback.<S>} onRejected
+ * @returns {Promise.<S>}
+ */
+Promise.prototype.fail = Promise.prototype['catch'];
+
+/**
+ * Returns resolving promise with given reason
+ *
+ * @method Promise.resolve
+ * @param {*} result - Resolved value
+ * @returns {Promise}
+ */
+
+/**
+ * Returns rejecting promise with given reason
+ *
+ * @method Promise.reject
+ * @param {Error} reason - Rejecting reason
+ * @returns {Promise}
+ */
+
+/**
+ * Returns a promise that is fulfilled with an array containing the fulfillment value of each promise,
+ * or is rejected with the same rejection reason as the first promise to be rejected.
+ *
+ * @method Promise.all
+ * @param {Array.<Promise.<*>|*>} promises
+ * @returns {Promise.<Array.<*>>}
+ */
+
+/**
+ * Returns a deferred object
+ *
+ * @method Promise.defer
+ * @returns {Deferred}
+ */
+Promise.defer = function() {
+  return new Deferred();
+};
+
+/**
+ * Deferred object
+ *
+ * @protected
+ * @constructor
+ */
+var Deferred = function() {
+  var self = this;
+  this.promise = new Promise(function(resolve, reject) {
+    self.resolve = resolve;
+    self.reject = reject;
+  });
+};
+
+/**
+ * Resolve promise
+ * @method Deferred#resolve
+ * @param {*} result - Resolving result
+ */
+
+/**
+ * Reject promise
+ * @method Deferred#reject
+ * @param {Error} error - Rejecting reason
+ */
+
+/**
+ *
+ */
+module.exports = Promise;