jsforce2 1.11.1

package/lib/api/streaming.js

@@ -0,0 +1,270 @@
+/**
+ * @file Manages Streaming APIs
+ * @author Shinichi Tomita <shinichi.tomita@gmail.com>
+ */
+
+'use strict';
+
+var events = require('events'),
+    inherits = require('inherits'),
+    _ = require('lodash/core'),
+    Faye   = require('faye'),
+    StreamingExtension = require('./streaming-extension'),
+    jsforce = require('../core');
+
+/**
+ * Streaming API topic class
+ *
+ * @class Streaming~Topic
+ * @param {Streaming} steaming - Streaming API object
+ * @param {String} name - Topic name
+ */
+var Topic = function(streaming, name) {
+  this._streaming = streaming;
+  this.name = name;
+};
+
+/**
+ * @typedef {Object} Streaming~StreamingMessage
+ * @prop {Object} event
+ * @prop {Object} event.type - Event type
+ * @prop {Record} sobject - Record information
+ */
+/**
+ * Subscribe listener to topic
+ *
+ * @method Streaming~Topic#subscribe
+ * @param {Callback.<Streaming~StreamingMesasge>} listener - Streaming message listener
+ * @returns {Subscription} - Faye subscription object
+ */
+Topic.prototype.subscribe = function(listener) {
+  return this._streaming.subscribe(this.name, listener);
+};
+
+/**
+ * Unsubscribe listener from topic
+ *
+ * @method Streaming~Topic#unsubscribe
+ * @param {Callback.<Streaming~StreamingMesasge>} listener - Streaming message listener
+ * @returns {Streaming~Topic}
+ */
+Topic.prototype.unsubscribe = function(listener) {
+  this._streaming.unsubscribe(this.name, listener);
+  return this;
+};
+
+/*--------------------------------------------*/
+
+/**
+ * Streaming API Generic Streaming Channel
+ *
+ * @class Streaming~Channel
+ * @param {Streaming} steaming - Streaming API object
+ * @param {String} name - Channel name (starts with "/u/")
+ */
+var Channel = function(streaming, name) {
+  this._streaming = streaming;
+  this._name = name;
+};
+
+/**
+ * Subscribe to channel
+ *
+ * @param {Callback.<Streaming~StreamingMessage>} listener - Streaming message listener
+ * @returns {Subscription} - Faye subscription object
+ */
+Channel.prototype.subscribe = function(listener) {
+  return this._streaming.subscribe(this._name, listener);
+};
+
+Channel.prototype.unsubscribe = function(listener) {
+  this._streaming.unsubscribe(this._name, listener);
+  return this;
+};
+
+Channel.prototype.push = function(events, callback) {
+  var isArray = _.isArray(events);
+  events = isArray ? events : [ events ];
+  var conn = this._streaming._conn;
+  if (!this._id) {
+    this._id = conn.sobject('StreamingChannel').findOne({ Name: this._name }, 'Id')
+      .then(function(rec) { return rec.Id });
+  }
+  return this._id.then(function(id) {
+    var channelUrl = '/sobjects/StreamingChannel/' + id + '/push';
+    return conn.requestPost(channelUrl, { pushEvents: events });
+  }).then(function(rets) {
+    return isArray ? rets : rets[0];
+  }).thenCall(callback);
+};
+
+/*--------------------------------------------*/
+
+/**
+ * Streaming API class
+ *
+ * @class
+ * @extends events.EventEmitter
+ * @param {Connection} conn - Connection object
+ */
+var Streaming = function(conn) {
+  this._conn = conn;
+};
+
+inherits(Streaming, events.EventEmitter);
+
+/** @private **/
+Streaming.prototype._createClient = function(forChannelName, extensions) {
+  // forChannelName is advisory, for an API workaround. It does not restrict or select the channel.
+  var needsReplayFix = typeof forChannelName === 'string' && forChannelName.indexOf('/u/') === 0;
+  var endpointUrl = [
+    this._conn.instanceUrl,
+    // special endpoint "/cometd/replay/xx.x" is only available in 36.0.
+    // See https://releasenotes.docs.salesforce.com/en-us/summer16/release-notes/rn_api_streaming_classic_replay.htm
+    "cometd" + (needsReplayFix === true && this._conn.version === "36.0" ? "/replay" : ""),
+    this._conn.version
+  ].join('/');
+  var fayeClient = new Faye.Client(endpointUrl, {});
+  fayeClient.setHeader('Authorization', 'OAuth '+this._conn.accessToken);
+  if (extensions instanceof Array) {
+    extensions.forEach(function(extension) {
+      fayeClient.addExtension(extension);
+    });
+  }
+  if (fayeClient._dispatcher.getConnectionTypes().indexOf('callback-polling') === -1) {
+    // prevent streaming API server error
+    fayeClient._dispatcher.selectTransport('long-polling');
+    fayeClient._dispatcher._transport.batching = false;
+  }
+  return fayeClient;
+};
+
+/** @private **/
+Streaming.prototype._getFayeClient = function(channelName) {
+  var isGeneric = channelName.indexOf('/u/') === 0;
+  var clientType = isGeneric ? 'generic' : 'pushTopic';
+  if (!this._fayeClients || !this._fayeClients[clientType]) {
+    this._fayeClients = this._fayeClients || {};
+    this._fayeClients[clientType] = this._createClient(channelName);
+  }
+  return this._fayeClients[clientType];
+};
+
+
+/**
+ * Get named topic
+ *
+ * @param {String} name - Topic name
+ * @returns {Streaming~Topic}
+ */
+Streaming.prototype.topic = function(name) {
+  this._topics = this._topics || {};
+  var topic = this._topics[name] =
+    this._topics[name] || new Topic(this, name);
+  return topic;
+};
+
+/**
+ * Get Channel for Id
+ * @param {String} channelId - Id of StreamingChannel object
+ * @returns {Streaming~Channel}
+ */
+Streaming.prototype.channel = function(channelId) {
+  return new Channel(this, channelId);
+};
+
+/**
+ * Subscribe topic/channel
+ *
+ * @param {String} name - Topic name
+ * @param {Callback.<Streaming~StreamingMessage>} listener - Streaming message listener
+ * @returns {Subscription} - Faye subscription object
+ */
+Streaming.prototype.subscribe = function(name, listener) {
+  var channelName = name.indexOf('/') === 0 ? name : '/topic/' + name;
+  var fayeClient = this._getFayeClient(channelName);
+  return fayeClient.subscribe(channelName, listener);
+};
+
+/**
+ * Unsubscribe topic
+ *
+ * @param {String} name - Topic name
+ * @param {Callback.<Streaming~StreamingMessage>} listener - Streaming message listener
+ * @returns {Streaming}
+ */
+Streaming.prototype.unsubscribe = function(name, listener) {
+  var channelName = name.indexOf('/') === 0 ? name : '/topic/' + name;
+  var fayeClient = this._getFayeClient(channelName);
+  fayeClient.unsubscribe(channelName, listener);
+  return this;
+};
+
+
+/**
+ * Create a Streaming client, optionally with extensions
+ *
+ * See Faye docs for implementation details: https://faye.jcoglan.com/browser/extensions.html
+ *
+ * Example usage:
+ * 
+ * ```javascript
+ * // Establish a Salesforce connection. (Details elided)
+ * const conn = new jsforce.Connection({ … });
+ * 
+ * const fayeClient = conn.streaming.createClient();
+ * 
+ * const subscription = fayeClient.subscribe(channel, data => {
+ *   console.log('topic received data', data);
+ * });
+ * 
+ * subscription.cancel();
+ * ```
+ * 
+ * Example with extensions, using Replay & Auth Failure extensions in a server-side Node.js app:
+ * 
+ * ```javascript
+ * // Establish a Salesforce connection. (Details elided)
+ * const conn = new jsforce.Connection({ … });
+ * 
+ * const channel = "/event/My_Event__e";
+ * const replayId = -2; // -2 is all retained events
+ * 
+ * const exitCallback = () => process.exit(1);
+ * const authFailureExt = new jsforce.StreamingExtension.AuthFailure(exitCallback);
+ * 
+ * const replayExt = new jsforce.StreamingExtension.Replay(channel, replayId);
+ * 
+ * const fayeClient = conn.streaming.createClient([
+ *   authFailureExt,
+ *   replayExt
+ * ]);
+ * 
+ * const subscription = fayeClient.subscribe(channel, data => {
+ *   console.log('topic received data', data);
+ * });
+ * 
+ * subscription.cancel();
+ * ```
+ * 
+ * @param {Array} Extensions - Optional, extensions to apply to the Faye client
+ * @returns {FayeClient} - Faye client object
+ */
+Streaming.prototype.createClient = function(extensions) {
+  return this._createClient(null, extensions);
+};
+
+/*--------------------------------------------*/
+/*
+ * Register hook in connection instantiation for dynamically adding this API module features
+ */
+jsforce.on('connection:new', function(conn) {
+  conn.streaming = new Streaming(conn);
+});
+
+/*
+ * 
+ */
+jsforce.StreamingExtension = StreamingExtension;
+
+module.exports = Streaming;

package/lib/api/tooling.js

@@ -0,0 +1,313 @@
+/**
+ * @file Manages Tooling APIs
+ * @author Shinichi Tomita <shinichi.tomita@gmail.com>
+ */
+
+'use strict';
+
+var jsforce = require('../core'),
+    _     = require('lodash/core'),
+    Cache = require('../cache');
+
+/**
+ * API class for Tooling API call
+ *
+ * @class
+ * @param {Connection} conn - Connection
+ */
+var Tooling = function(conn) {
+  this._conn = conn;
+  this._logger = conn._logger;
+  var delegates = [
+    "query",
+    "queryMore",
+    "_toRecordResult",
+    "create",
+    "_createSingle",
+    "_createParallel",
+    "_createMany",
+    "insert",
+    "retrieve",
+    "_retrieveSingle",
+    "_retrieveParallel",
+    "_retrieveMany",
+    "update",
+    "_updateSingle",
+    "_updateParallel",
+    "_updateMany",
+    "upsert",
+    "del",
+    "delete",
+    "destroy",
+    "_destroySingle",
+    "_destroyParallel",
+    "_destroyMany",
+    "describe",
+    "describeGlobal",
+    "sobject"
+  ];
+  delegates.forEach(function(method) {
+    this[method] = conn.constructor.prototype[method];
+  }, this);
+
+  this.cache = new Cache();
+
+  var cacheOptions = {
+    key: function(type) { return type ? "describe." + type : "describe"; }
+  };
+  this.describe$ = this.cache.makeCacheable(this.describe, this, cacheOptions);
+  this.describe = this.cache.makeResponseCacheable(this.describe, this, cacheOptions);
+  this.describeSObject$ = this.describe$;
+  this.describeSObject = this.describe;
+
+  cacheOptions = { key: 'describeGlobal' };
+  this.describeGlobal$ = this.cache.makeCacheable(this.describeGlobal, this, cacheOptions);
+  this.describeGlobal = this.cache.makeResponseCacheable(this.describeGlobal, this, cacheOptions);
+
+  this.initialize();
+};
+
+/**
+ * Initialize tooling API
+ * @protected
+ */
+Tooling.prototype.initialize = function() {
+  this.sobjects = {};
+  this.cache.clear();
+  this.cache.get('describeGlobal').removeAllListeners('value');
+  this.cache.get('describeGlobal').on('value', _.bind(function(res) {
+    if (res.result) {
+      var types = _.map(res.result.sobjects, function(so) { return so.name; });
+      types.forEach(this.sobject, this);
+    }
+  }, this));
+};
+
+/**
+ * @private
+ */
+Tooling.prototype._baseUrl = function() {
+  return this._conn._baseUrl() + "/tooling";
+};
+
+/**
+ * @private
+ */
+Tooling.prototype._supports = function(feature) {
+  // should return false in order not to use compsite collection
+  if (feature === 'sobject-collection') {
+    return false;
+  }
+  return this._conn._supports.apply(this._conn, arguments);
+};
+
+/**
+ * @private
+ */
+Tooling.prototype.request = function() {
+  return this._conn.request.apply(this._conn, arguments);
+};
+
+/**
+ * Execute query by using SOQL
+ *
+ * @param {String} soql - SOQL string
+ * @param {Callback.<QueryResult>} [callback] - Callback function
+ * @returns {Query.<QueryResult>}
+ */
+/**
+ * Query next record set by using query locator
+ *
+ * @method Tooling#query
+ * @param {String} locator - Next record set locator
+ * @param {Callback.<QueryResult>} [callback] - Callback function
+ * @returns {Query.<QueryResult>}
+ */
+/**
+ * Retrieve specified records
+ *
+ * @method Tooling#queryMore
+ * @param {String} type - SObject Type
+ * @param {String|Array.<String>} ids - A record ID or array of record IDs
+ * @param {Callback.<Record|Array.<Record>>} [callback] - Callback function
+ * @returns {Promise.<Record|Array.<Record>>}
+ */
+
+/**
+ * Synonym of Tooling#create()
+ *
+ * @method Tooling#insert
+ * @param {String} type - SObject Type
+ * @param {Object|Array.<Object>} records - A record or array of records to create
+ * @param {Callback.<RecordResult|Array.<RecordResult>>} [callback] - Callback function
+ * @returns {Promise.<RecordResult|Array.<RecordResult>>}
+ */
+/**
+ * Create records
+ *
+ * @method Tooling#create
+ * @param {String} type - SObject Type
+ * @param {Record|Array.<Record>} records - A record or array of records to create
+ * @param {Callback.<RecordResult|Array.<RecordResult>>} [callback] - Callback function
+ * @returns {Promise.<RecordResult|Array.<RecordResult>>}
+ */
+
+/**
+ * Update records
+ *
+ * @method Tooling#update
+ * @param {String} type - SObject Type
+ * @param {Record|Array.<Record>} records - A record or array of records to update
+ * @param {Callback.<RecordResult|Array.<RecordResult>>} [callback] - Callback function
+ * @returns {Promise.<RecordResult|Array.<RecordResult>>}
+ */
+
+/**
+ * Upsert records
+ *
+ * @method Tooling#upsert
+ * @param {String} type - SObject Type
+ * @param {Record|Array.<Record>} records - Record or array of records to upsert
+ * @param {String} extIdField - External ID field name
+ * @param {Callback.<RecordResult|Array.<RecordResult>>} [callback] - Callback
+ * @returns {Promise.<RecordResult|Array.<RecordResult>>}
+ */
+
+/**
+ * Synonym of Tooling#destroy()
+ *
+ * @method Tooling#delete
+ * @param {String} type - SObject Type
+ * @param {String|Array.<String>} ids - A ID or array of IDs to delete
+ * @param {Callback.<RecordResult|Array.<RecordResult>>} [callback] - Callback
+ * @returns {Promise.<RecordResult|Array.<RecordResult>>}
+ */
+/**
+ * Synonym of Tooling#destroy()
+ *
+ * @method Tooling#del
+ * @param {String} type - SObject Type
+ * @param {String|Array.<String>} ids - A ID or array of IDs to delete
+ * @param {Callback.<RecordResult|Array.<RecordResult>>} [callback] - Callback
+ * @returns {Promise.<RecordResult|Array.<RecordResult>>}
+ */
+/**
+ * Delete records
+ *
+ * @method Tooling#destroy
+ * @param {String} type - SObject Type
+ * @param {String|Array.<String>} ids - A ID or array of IDs to delete
+ * @param {Callback.<RecordResult|Array.<RecordResult>>} [callback] - Callback
+ * @returns {Promise.<RecordResult|Array.<RecordResult>>}
+ */
+
+/**
+ * Synonym of Tooling#describe()
+ *
+ * @method Tooling#describeSObject
+ * @param {String} type - SObject Type
+ * @param {Callback.<DescribeSObjectResult>} [callback] - Callback function
+ * @returns {Promise.<DescribeSObjectResult>}
+ */
+/**
+ * Describe SObject metadata
+ *
+ * @method Tooling#describe
+ * @param {String} type - SObject Type
+ * @param {Callback.<DescribeSObjectResult>} [callback] - Callback function
+ * @returns {Promise.<DescribeSObjectResult>}
+ */
+
+/**
+ * Describe global SObjects
+ *
+ * @method Tooling#describeGlobal
+ * @param {Callback.<DescribeGlobalResult>} [callback] - Callback function
+ * @returns {Promise.<DescribeGlobalResult>}
+ */
+
+/**
+ * Get SObject instance
+ *
+ * @method Tooling#sobject
+ * @param {String} type - SObject Type
+ * @returns {SObject}
+ */
+
+/**
+ * @typedef {Object} Tooling~ExecuteAnonymousResult
+ * @prop {Boolean} compiled - Flag if the query is compiled successfully
+ * @prop {String} compileProblem - Error reason in compilation
+ * @prop {Boolean} success - Flag if the code is executed successfully
+ * @prop {Number} line - Line number for the error
+ * @prop {Number} column - Column number for the error
+ * @prop {String} exceptionMessage - Exception message
+ * @prop {String} exceptionStackTrace - Exception stack trace
+ */
+/**
+ * Executes Apex code anonymously
+ *
+ * @param {String} body - Anonymous Apex code
+ * @param {Callback.<Tooling~ExecuteAnonymousResult>} [callback] - Callback function
+ * @returns {Promise.<Tooling~ExecuteAnonymousResult>}
+ */
+Tooling.prototype.executeAnonymous = function(body, callback) {
+  var url = this._baseUrl() + "/executeAnonymous?anonymousBody=" + encodeURIComponent(body);
+  return this.request(url).thenCall(callback);
+};
+
+/**
+ * Executes Apex tests asynchronously
+ *
+ * @param {Array.<String>} classids - Comma separated list of class IDs
+ * @param {Callback.<Tooling~ExecuteAnonymousResult>} [callback] - Callback function
+ * @returns {Promise.<Tooling~ExecuteAnonymousResult>}
+ */
+Tooling.prototype.runTestsAsynchronous = function(classids, callback) {
+  var url = this._baseUrl() + "/runTestsAsynchronous/";
+  return this._conn.requestPost(url, {classids : classids.join(',')}, undefined, callback);
+};
+
+/**
+ * Executes Apex tests synchronously
+ *
+ * @param {Array.<String>} classnames - Comma separated list of class Names
+ * @param {Callback.<Tooling~ExecuteAnonymousResult>} [callback] - Callback function
+ * @returns {Promise.<Tooling~ExecuteAnonymousResult>}
+ */
+Tooling.prototype.runTestsSynchronous = function(classnames, callback) {
+  var url = this._baseUrl() + "/runTestsSynchronous/";
+  return this._conn.requestPost(url, {classnames : classnames.join(',')}, undefined, callback);
+};
+
+/**
+ * @typedef {Object} Tooling~CompletionsResult
+ * @prop {Object} publicDeclarations
+ */
+/**
+ * Retrieves available code completions of the referenced type
+ *
+ * @param {String} [type] - completion type (default 'apex')
+ * @param {Callback.<Tooling~CompletionsResult>} [callback] - Callback function
+ * @returns {Promise.<Tooling~CompletionsResult>}
+ */
+Tooling.prototype.completions = function(type, callback) {
+  if (!_.isString(type)) {
+    callback = type;
+    type = 'apex';
+  }
+  var url = this._baseUrl() + "/completions?type=" + encodeURIComponent(type);
+  return this.request(url).thenCall(callback);
+};
+
+
+/*--------------------------------------------*/
+/*
+ * Register hook in connection instantiation for dynamically adding this API module features
+ */
+jsforce.on('connection:new', function(conn) {
+  conn.tooling = new Tooling(conn);
+});
+
+
+module.exports = Tooling;

package/lib/browser/canvas.js

@@ -0,0 +1,90 @@
+/*global Sfdc */
+'use strict';
+
+var Duplex = require('readable-stream').Duplex,
+    _ = require('lodash/core');
+
+function parseHeaders(hs) {
+  var headers = {};
+  hs.split(/\n/).forEach(function(line) {
+    var pair = line.split(/\s*:\s*/);
+    var name = pair[0].toLowerCase();
+    var value = pair[1];
+    headers[name] = value;
+  });
+  return headers;
+}
+
+module.exports = {
+
+  supported: typeof Sfdc === 'object' && typeof Sfdc.canvas !== 'undefined',
+
+  createRequest: function(signedRequest) {
+    return function(params, callback) {
+      var response;
+      var str = new Duplex();
+      str._read = function(size) {
+        if (response) {
+          str.push(response.body);
+        }
+      };
+      var bufs = [];
+      var sent = false;
+      str._write = function(chunk, encoding, callback) {
+        bufs.push(chunk.toString(encoding));
+        callback();
+      };
+      str.on('finish', function() {
+        if (!sent) {
+          send(bufs.join(''));
+          sent = true;
+        }
+      });
+      if (params.body || params.body === "" || !/^(put|post|patch)$/i.test(params.method)) {
+        send(params.body);
+        sent = true;
+      }
+
+      function send(body) {
+        var settings = {
+          client: signedRequest.client,
+          method: params.method,
+          data: body
+        };
+        if (params.headers) {
+          settings.headers = {};
+          for (var name in params.headers) {
+            if (name.toLowerCase() === 'content-type') {
+              settings.contentType = params.headers[name];
+            } else {
+              settings.headers[name] = params.headers[name];
+            }
+          }
+        }
+        settings.success = function(data) {
+          var headers = parseHeaders(data.responseHeaders);
+          var body = data.payload;
+          if (!_.isString(body)) {
+            body = JSON.stringify(body);
+          }
+          response = {
+            statusCode : data.status,
+            headers: headers,
+            body: body
+          };
+          if (callback) {
+            callback(null, response, response.body);
+          }
+          str.end();
+        };
+        settings.failure = function(err) {
+          if (callback) {
+            callback(err);
+          }
+        };
+        Sfdc.canvas.client.ajax(params.url, settings);
+      }
+      return str;
+    };
+  }
+};