Merge pull request #76 from smartsheet-platform/enterprise-events

Add enterprise events endpoint

.travis.yml

@@ -1,8 +1,7 @@
 language: node_js
 
 node_js:
-  - "lts/boron"
-  - "lts/argon"
+  - "lts/carbon"
 
 before_install:
   - git clone https://github.com/smartsheet-platform/smartsheet-sdk-tests.git

ADVANCED.md

@@ -0,0 +1,70 @@
+# Advanced Topics for the Smartsheet SDK for Javascript
+
+## Event Reporting
+The following sample demonstrates best practices for consuming the event stream returned from the Smartsheet Event Reporting feature. 
+
+The sample uses the `smartsheet.events.getEvents` method to request lists of events from the stream. The first request sets the `since` parameter with the point in time (i.e. event occurrence datetime) in the stream from which to start consuming events. The `since` parameter can be set with a datetime value that is either formatted as ISO 8601 (e.g. 2010-01-01T00:00:00Z) or as UNIX epoch (in which case the `numericDates` parameter must also be set to `true`. By default the `numericDates` parameter is set to `false`).
+
+To consume the next list of events after the initial list of events is returned, set the `streamPosition` parameter with the `nextStreamPosition` attribute obtained from the previous request and don't set the `since` parameter with any values. This is because when using the `get` method, either the `since` parameter or the `streamPosition` parameter should be set, but never both. 
+
+Note that the `moreAvailable` attribute in a response indicates whether more events are immediately available for consumption. If events aren't immediately available, they may still be generating so subsequent requests should keep using the same `streamPosition` value until the next list of events is retrieved.
+
+Many events have additional information available as a part of the event. That information can be accessed from the data stored in the `additionalDetails` attribute. Information about the additional details provided can be found [here](https://smartsheet-platform.github.io/event-reporting-docs/).
+
+
+```javascript
+// Initialize the client
+var client = require('smartsheet');
+var smartsheet = client.createClient({
+  accessToken: '1234',
+  logLevel: 'info'
+});
+
+const currentDate = new Date();
+const dateWeekAgo = currentDate.setDate(currentDate.getDate() - 7);
+// The first call to the events reporting API
+// requires the since query parameter.
+// If you pass in an UNIX epoch date, numericDates must be true
+let options = {
+  queryParameters: {
+    since: dateWeekAgo,
+    maxCount: 10,
+    numericDates: true
+  }
+}
+
+function getEvents(options) {
+  smartsheet.events.getEvents(options)
+  .then((result) => {
+    printNewSheetEvents(result);
+    getNextStreamOfEvents(result.moreAvailable, result.nextStreamPosition);
+  })
+  .catch((error) => console.log(JSON.stringify(error)));
+}
+
+function getNextStreamOfEvents(moreEventsAvailable, nextStreamPosition) {
+  // Subsequent calls require the streamPosition property
+  options = {
+    queryParameters: {
+      streamPosition: nextStreamPosition,
+      maxCount: 10
+    }
+  }
+
+  if (moreEventsAvailable) {
+    getEvents(options);
+  } 
+}
+
+// This example is looking specifically for new sheet events
+function printNewSheetEvents(result) {
+  // Find all created sheets
+  result.data.forEach(function (item) {
+    if (item.objectType === "SHEET" && item.action === "CREATE") {
+      console.log(item.additionalDetails.sheetName)
+    }
+  })
+}
+
+getEvents(options);
+```

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+## 2.77.0 - May 9, 2019
+- Added events endpoint to retrieve events that are occurring in your Smartsheet plan.
+
 ## 1.5.0 - February 18, 2019
 - Updated documentation regarding the usage of baseUrl to clarify how clients can access smartsheetgov
 - Added constant for smartsheetgov

README.md

@@ -219,11 +219,19 @@ var responsePromise = smartsheet.request.post({
 });
 ```
 
+## Advanced Topics
+For details about more advanced features, see [Advanced Topics](ADVANCED.md).
+
 ## Contributing
 
 If you would like to contribute a change to the SDK, please fork a branch and then submit a pull request.
 [More info here.](https://help.github.com/articles/using-pull-requests)
 
+## Version Numbers
+Starting from the v2.77.0 release, Smartsheet SDKs will use a new versioning strategy. Since all users are on the Smartsheet API 2.0, the SDK version numbers will start with 2. The 2nd number will be an internal reference number. The 3rd number is for incremental changes. 
+
+For example, v2.77.0 means that you are using our 2.0 version of the API, the API is synched internally to a tag of 77, and then if there are numbers after the last decimal, that will indicate a minor change.
+
 ## Support
 
 If you have any questions or issues with this SDK please post on [Stack Overflow using the tag "smartsheet-api"](http://stackoverflow.com/questions/tagged/smartsheet-api) or contact us directly at [email protected].

index.js

@@ -87,6 +87,7 @@ exports.createClient = function(clientOptions) {
   return {
     constants  : require('./lib/utils/constants.js'),
     contacts   : require('./lib/contacts/').create(options),
+    events     : require('./lib/events/').create(options),
     favorites  : require('./lib/favorites/').create(options),
     folders    : require('./lib/folders/').create(options),
     groups     : require('./lib/groups/').create(options),
@@ -108,5 +109,5 @@ exports.createClient = function(clientOptions) {
 
 exports.smartSheetURIs = {
   defaultBaseURI: 'https://api.smartsheet.com/2.0/',
-  govBaseURI: 'https://api.smartsheetgov.com/2.0'
+  govBaseURI: 'https://api.smartsheetgov.com/2.0/'
 }

lib/events/index.js

@@ -0,0 +1,17 @@
+var _ = require('underscore');
+
+exports.create = function(options) {
+  var requestor = options.requestor;
+
+  var optionsToSend = {
+    url: options.apiUrls.events
+  };
+  _.extend(optionsToSend, options.clientOptions);
+
+  var getEvents = (getOptions, callback) =>
+    requestor.get(_.extend({}, optionsToSend, getOptions), callback);
+
+  return {
+    getEvents : getEvents
+  };
+};

lib/utils/apis.js

@@ -1,5 +1,6 @@
 module.exports = {
   contacts         :  'contacts/',
+  events           :  'events/',
   favorites        :  'favorites/',
   folders          :  'folders/',
   groups           :  'groups/',

package.json

@@ -1,6 +1,6 @@
 {
   "name": "smartsheet",
-  "version": "1.5.0",
+  "version": "2.77.0",
   "description": "Smartsheet JavaScript client SDK",
   "main": "index.js",
   "scripts": {

test/functional/client_test.js

@@ -39,6 +39,17 @@ describe('Client Unit Tests', function() {
     });
   });
 
+  describe('#Events', function() {
+    it('should have Events object', function() {
+      smartsheet.should.have.property('events');
+      Object.keys(smartsheet.events).should.be.length(1);
+    });
+
+    it('should have Events GET methods', function() {
+      smartsheet.events.should.have.property('getEvents');
+    });
+  });
+
   describe('#Favorites', function() {
     it('should have Favorites object',function(){
       smartsheet.should.have.property('favorites');

test/functional/endpoints_test.js

@@ -15,6 +15,12 @@ describe('Method Unit Tests', function () {
                 { name: 'listContacts', stub: 'get', options: undefined, expectedRequest: {url: "contacts/" }},
             ]
         },
+        {
+            name: 'events',
+            methods: [
+                { name: 'getEvents', stub: 'get', options: {}, expectedRequest: {url: "events/" }}
+            ]
+        },
         {
             name: 'favorites',
             methods: [