chore: add js doc strings

lib/contacts/index.js

@@ -1,5 +1,22 @@
 var _ = require('underscore');
 
+/**
+ * @typedef Contact
+ * @type {object}
+ * @property {string} id - contact id
+ * @property {string} name - full name of the contact
+ * @property {string} email - contact's email address
+ */
+
+/**
+ * @typedef ListContactsResponse
+ * @property {number} pageNumber - number of pages of results that match the query.
+ * @property {number} pageSize - number of results on each page.
+ * @property {number} totalPages - number of pages of results that match the query.
+ * @property {number} totalCount - number of contacts that match the query.
+ * @property {Contact[]} data - Array of contacts representing this page of results.
+ */
+
 exports.create = function(options) {
   var requestor = options.requestor;
 
@@ -9,11 +26,41 @@ exports.create = function(options) {
   _.extend(optionsToSend, options.clientOptions);
 
 
+  /**
+   * @function getContact
+   * @description Function to get one contact the user has access to using the 
+   * contact id.
+   * @param {number} getOptions.id - id of the contact to return.
+   * @param {string} getOptions.queryParameters - comma-separated list of optional elements to
+   * include in the response. Ex: "profileImage"
+   * @param {function} callback 
+   * @returns {Contact}
+   */
   var getContact = (getOptions, callback) =>
     requestor.get(_.extend({}, optionsToSend, getOptions), callback);
 
+  /**
+   * @function listContacts
+   * @description Lists all of the contacts that the user has access to
+   * that meet any of the optional filtering criteria. Note that this call is paginated
+   * unless the `includeAll` flag is set to false.
+   * @param {boolean | undefined} getOptions.queryParameters.includeAll - The return will not be paginated if this is
+   * set to true. Defaults to `false`.
+   * @param {string | number | undefined} getOptions.queryParameters.modifiedSince - When passed only contacts modified 
+   * after the passed datetime will be returned.
+   * @param {boolean | undefined} getOptions.queryParameters.numericDates - You can optionally chose to send
+   * and receive dates in the numeric format (ms since the UNIX epoch). Defaults to `false`.
+   * @param {number | undefined} getOptions.queryParameters.page - Which page of results to return. Defaults to `1`.
+   * @param {number | undefined} getOptions.queryParameters.pageSize - The maximum number of results to return per page.
+   * Defaults to `100`.
+   * @param {Function} callback 
+   * @returns {ListContactsResponse}
+   */
+  var listContacts = (getOptions, callback) =>
+    requestor.get(_.extend({}, optionsToSend, getOptions), callback);
+
   return {
     getContact : getContact,
-    listContacts : getContact
+    listContacts : listContacts
   };
 };

lib/events/index.js

@@ -1,5 +1,32 @@
 var _ = require('underscore');
 
+/**
+ * @typedef Event
+ * @type {object}
+ * @param {string} eventId - Id of the event
+ * @param {string} objectType - The smartsheet resource impacted by the event.
+ * Either `SHEET` or `WORKSPACE`.
+ * @param {string} action - The action applied to the object. Ex: `CREATE` or `DELETE`
+ * @param {string} objectId - Id of the object impacted by the action.
+ * @param {string} eventTimeStamp - Datetime of the event. Defaults to ISO-8601 format.
+ * @param {string} userId - Id of the user who initiated the event.
+ * @param {number} requestUserId - Id of the user whose id is embedded in the request
+ * that initiated the event.
+ * @param {number | null} accessTokenName - Name of the access token that initiated the action.
+ * @param {string} source - Identifies the type of action that triggered the event.
+ * @param {object} additionalDetails - Container object with additional event specific properties.
+ */
+
+/**
+ * @typedef EventResponse
+ * @type {object}
+ * @property {string} nextStreamPosition - This string should be passed in a subsequent call
+ * to get the next stream of events.
+ * @property {boolean} moreAvailable - `true` if there are more results available in the next
+ * stream.
+ * @property {Event[]} data - Array of events in this stream. 
+ */
+
 exports.create = function(options) {
   var requestor = options.requestor;
 
@@ -8,6 +35,26 @@ exports.create = function(options) {
   };
   _.extend(optionsToSend, options.clientOptions);
 
+  /**
+   * @function getEvents
+   * @description Gets events that are occurring in your Smartsheet organization account.
+   * Examples of events are creation, update, load, and delete of sheets, reports, dashboards,
+   * attachments, users, etc.
+   * @param {string | undefined} getOptions.queryParameters.since When provided will return
+   * events that occured after the specified datetime. Interpreted as ISO-8601 format, unless
+   * numericDates is specified (see details about numericDates below). Should not be set
+   * if a `streamPosition` is set.
+   * @param {string | undefined} getOptions.queryParameters.streamPosition - Indiates the next
+   * set of events to be returned. You must pass a `streamPosition` OR `since`.
+   * @param {number | undefined} getOptions.queryParameters.maxCount - Maximum number of 
+   * events to return in a call. Must be between 1 and 10,000 inclusive. Defaults to 1000.
+   * @param {boolean | undefined} getOptions.queryParameters.numericDates - If `true` dates
+   * are accepted and returned in UNIX epoch time. Defaults to `false`.
+   * @param {number | undefined} getOptions.queryParameters.managedPlanId - The target 
+   * managed plan to list events for.
+   * @param {Function} callback 
+   * @returns {EventResponse}
+   */
   var getEvents = (getOptions, callback) =>
     requestor.get(_.extend({}, optionsToSend, getOptions), callback);
 

lib/favorites/index.js

@@ -1,6 +1,41 @@
 var _ = require('underscore');
 var types = require('../utils/constants').types;
 
+/**
+ * @typedef Favorite
+ * @type {object}
+ * @property {number} objectId - Id of the favorited object.
+ * @property {string} type - Type of the favorited asset.
+ * `folder` `report` `sheet` `sight` `template` `workspace`
+ */
+
+/**
+ * @typedef GetFavoritesResponse
+ * @type {object}
+ * @property {number} pageNumber - The current page of favorites.
+ * @property {number | null} pageSize - The number of favorites per page.
+ * @property {number} totalPages - The number of pages of favorites for the request.
+ * @property {number} totalCount - Total number of favorites.
+ * @property {Favorite[]} data - list of favorites on the current page.
+ */
+
+/**
+ * @typedef AddFavoritesResponse
+ * @type {object}
+ * @property {string} message - Message indicating the success of the request. `PARTIAL_SUCCESS` or `SUCCESS`.
+ * @property {number} resultCode - Number indicating the success of the request. `0` indicates success. `3` 
+ * indicates partial success.
+ * @property {Favorite | Favorite[]} result - favorite(s) that were added successfully.
+ */
+
+/**
+ * @typedef DeleteFavoritesResponse
+ * @type {object}
+ * @property {string} message - Message indicating the success of the request. `PARTIAL_SUCCESS` or `SUCCESS`.
+ * @property {number} resultCode - Number indicating the success of the request. `0` indicates success. `3` 
+ * indicates partial success.
+ */
+
 exports.create = options => {
   var requestor = options.requestor;
 
@@ -9,9 +44,31 @@ exports.create = options => {
   };
   _.extend(optionsToSend, options.clientOptions);
 
+  /**
+   * @function listFavorites
+   * @description Gets a list of all of the user's favorite assets
+   * @param {boolean | undefined} getOptions.queryParameters.includeAll - If `true` it will not 
+   * paginate and all favorites will be returned in one request. Defaults to `false`.
+   * @param {number | undefined} getOptions.queryParameters.page - Which page of results to return. 
+   * Defaults to `1`.
+   * @param {number | undefined} getOptions.queryParameters.pageSize - Maximum number of results returned
+   * in one page. Defaults to `100`.
+   * @param {string | undefined} getOptions.queryParameters.include - Comma separated list of optional 
+   * elements to include in the response. Ex: `directId` or `name`.
+   * @param {Function} callback 
+   * @returns {GetFavoritesResponse}
+   */
   var listFavorites = (getOptions, callback) =>
     requestor.get(_.extend({}, optionsToSend, getOptions), callback);
 
+  /**
+   * @function addItemsToFavorites
+   * @description Method to add one or more favorite items for the user.
+   * @param {Favorite | Favorite[]} postOptions.body - A single asset or a list of assets that you
+   * want to add as favorites.
+   * @param {Function} callback 
+   * @returns {AddFavoritesResponse}
+   */
   var addItemsToFavorites = (postOptions, callback) =>
     requestor.post(_.extend({}, optionsToSend, postOptions), callback);
 
@@ -31,18 +88,68 @@ exports.create = options => {
     };
   };
 
+  /**
+   * @function addSheetToFavorites
+   * @description Method to favorite one sheet.
+   * @param {string} postOptions.objectId - Id of the sheet you would like to favorite.
+   * @param {Function} callback
+   * @returns {AddFavoritesResponse}
+   */
   var addSheetToFavorites = buildFavoriteAddition(types.sheet);
 
+  /**
+   * @function addFolderToFavorites
+   * @description Method to favorite one folder.
+   * @param {string} postOptions.objectId - Id of the folder you would like to favorite.
+   * @param {Function} callback
+   * @returns {AddFavoritesResponse}
+   */
   var addFolderToFavorites = buildFavoriteAddition(types.folder);
 
+  /**
+   * @function addReportToFavorites
+   * @description Method to favorite one report.
+   * @param {string} postOptions.objectId - Id of the report you would like to favorite.
+   * @param {Function} callback
+   * @returns {AddFavoritesResponse}
+   */
   var addReportToFavorites = buildFavoriteAddition(types.report);
 
+  /**
+   * @function addTemplateToFavorites
+   * @description Method to favorite one template.
+   * @param {string} postOptions.objectId - Id of the template you would like to favorite.
+   * @param {Function} callback
+   * @returns {AddFavoritesResponse}
+   */
   var addTemplateToFavorites = buildFavoriteAddition(types.template);
 
+  /**
+   * @function addWorkspaceToFavorites
+   * @description Method to favorite one workspace.
+   * @param {string} postOptions.objectId - Id of the workspace you would like to favorite.
+   * @param {Function} callback
+   * @returns {AddFavoritesResponse}
+   */
   var addWorkspaceToFavorites = buildFavoriteAddition(types.workspace);
 
+  /**
+   * @function addSightToFavorites
+   * @description Method to favorite one sight.
+   * @param {string} postOptions.objectId - Id of the sight you would like to favorite.
+   * @param {Function} callback
+   * @returns {AddFavoritesResponse}
+   */
   var addSightToFavorites = buildFavoriteAddition(types.sight);
 
+  /**
+   * @function addMultipleToFavorites
+   * @description Method to add one or more favorite items for the user.
+   * @param {Favorite[]} postOptions.body - A list of assets that you
+   * want to add as favorites.
+   * @param {Function} callback 
+   * @returns {AddFavoritesResponse}
+   */
   var addMultipleToFavorites = (postOptions, callback) => {
     return requestor.post(_.extend({}, optionsToSend, postOptions), callback);
   };
@@ -65,16 +172,64 @@ exports.create = options => {
     };
   };
 
+  /**
+   * @function removeSheetFromFavorites
+   * @description Remove one or multiple sheets from favorites.
+   * Only one of the id parameters below must be set.
+   * @param {string[] | undefined} deleteOptions.queryParameters.objectIds - An array of ids of sheets to be removed from favorites.
+   * @param {string | undefined} deleteOptions.id - Id of a sheet that should be removed from favorites.
+   * @param {Function} callback
+   * @returns {DeleteFavoritesResponse}
+   */
   var removeSheetFromFavorites = buildFavoriteRemoval(types.sheet);
 
+  /**
+   * @function removeFolderFromFavorites
+   * @description Remove one or multiple folders from favorites.
+   * @param {string[] | undefined} deleteOptions.queryParameters.objectIds - An array of ids of folders to be removed from favorites.
+   * @param {string | undefined} deleteOptions.id - Id of a sheet that should be removed from favorites.
+   * @param {Function} callback
+   * @returns {DeleteFavoritesResponse}
+   */
   var removeFolderFromFavorites = buildFavoriteRemoval(types.folder);
 
+  /**
+   * @function removeReportFromFavorites
+   * @description Remove one or multiple reports from favorites.
+   * @param {string[] | undefined} deleteOptions.queryParameters.objectIds - An array of ids of reports to be removed from favorites.
+   * @param {string | undefined} deleteOptions.id - Id of a report that should be removed from favorites.
+   * @param {Function} callback
+   * @returns {DeleteFavoritesResponse}
+   */
   var removeReportFromFavorites = buildFavoriteRemoval(types.report);
 
+  /**
+   * @function removeTemplateFromFavorites
+   * @description Remove one or multiple templates from favorites.
+   * @param {string[] | undefined} objectIds - An array of ids of templates to be removed from favorites.
+   * @param {string | undefined} id - Id of a template that should be removed from favorites.
+   * @returns {DeleteFavoritesResponse}
+   */
   var removeTemplateFromFavorites = buildFavoriteRemoval(types.template);
 
+  /**
+   * @function removeWorkspaceFromFavorites
+   * @description Remove one or multiple workspaces from favorites.
+   * @param {string[] | undefined} deleteOptions.queryParameters.objectIds - an array of ids of workspaces to be removed from favorites.
+   * @param {string | undefined} deleteOptions.id - Id of a workspace that should be removed from favorites.
+   * @param {Function} callback
+   * @returns {DeleteFavoritesResponse}
+   */
   var removeWorkspaceFromFavorites = buildFavoriteRemoval(types.workspace);
 
+  /**
+   * @function removeSightFromFavorites
+   * @description Remove one or multiple Sights from favorites.
+   * @param {string[] | undefined} deleteOptions.queryParameters.objectIds - an array of ids of sights to be removed from favorites.
+   * @param {string | undefined} deleteOptions.id - Id of a sight that should be removed from favorites.
+   * @param {Function} callback
+   * @returns {DeleteFavoritesResponse}
+   */
   var removeSightFromFavorites = buildFavoriteRemoval(types.sight);
 
   return {

lib/server/index.js

@@ -1,13 +1,26 @@
 var _ = require('underscore');
 
+/**
+ * @typedef ServerInfoResponse
+ * @type {object}
+ * @property {object} formats - object to hold various formatting information.
+ * The structure of this object is not guarenteed to stay the same even within the same major api version.
+ * @property {string[]} supportedLocales - Array of string representing the locales Smartsheet supports.
+ */
+
 exports.create = function(options) {
   var optionsToSend = {
     url: options.apiUrls.server,
     urls : options.apiUrls,
   };
   _.extend(optionsToSend, options.clientOptions);
 
-
+  /**
+   * @function getInfo
+   * @description get static reference data from the server.
+   * @param {Function} callback 
+   * @returns {ServerInfoResponse}
+   */
   var getInfo = (getOptions, callback) =>
     options.requestor.get(_.extend({}, optionsToSend, getOptions), callback);