Merge pull request #189 from SparkPost/wip-2.0.0

Releasing version 2.0.0

.eslintrc

@@ -0,0 +1,6 @@
+{
+  "extends": "sparkpost/api",
+  "globals": {
+    "Promise": true
+  }
+}

.jshintrc

@@ -1,6 +1,7 @@
 {
   "node"               : true,
   "es3"                : false,
+  "esnext"             : true,
   "strict"             : true,
   "curly"              : true,
   "eqeqeq"             : true,

.travis.yml

@@ -1,12 +1,10 @@
 language: node_js
 node_js:
-- '4.1'
-- '4.0'
-- '0.12'
-- '0.10'
-before_install: npm install -g grunt-cli
-install: npm install
-script: "npm run-script ci"
+  - '4'
+  - '5'
+  - '6'
+after_success:
+  - npm run coveralls
 notifications:
   slack:
     secure: dsz+D/TuylEi+6zqdB5dVqyMlpbpafaBBcAwYIijTK6LuG8KdIdGNSFVX1ro6o3bJFwMvtfxNeK1eFrMy8l6VHZQL0dkXWRmCl/pxLhEntUiYTDwDOtiqy1QLZtv5AqtsdSr1qLiOJtgF6gXk66xipnV2UzjLVVoxzSrdOSnX4U=

CHANGELOG.md

@@ -4,6 +4,31 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased][unreleased]
 
+## [2.0.0] - 2016-11-04 - *breaking*
+- [#188](https://github.com/SparkPost/node-sparkpost/pull/188) Added setting debug in initialization (@aydrian)
+- [#186](https://github.com/SparkPost/node-sparkpost/pull/186) Return full body for sparkpost requests (@aydrian)
+- [#184](https://github.com/SparkPost/node-sparkpost/pull/184) Standardized action verbs on remaining libraries (@aydrian)
+- [#183](https://github.com/SparkPost/node-sparkpost/pull/183) Standardized action verbs for Webhooks (@aydrian)
+- [#181](https://github.com/SparkPost/node-sparkpost/pull/181) Removed toApiFormat (@aydrian)
+- [#177](https://github.com/SparkPost/node-sparkpost/pull/177) Refactored inbound domains library (@aydrian)
+- [#173](https://github.com/SparkPost/node-sparkpost/pull/173) Updated tests and examples for transmissions (@aydrian)
+- [#172](https://github.com/SparkPost/node-sparkpost/pull/172) Refactored subaccounts library (@aydrian)
+- [#171](https://github.com/SparkPost/node-sparkpost/pull/171) Refactored relay webhooks library (@aydrian)
+- [#170](https://github.com/SparkPost/node-sparkpost/pull/170) Refactored webhooks library (@aydrian)
+- [#169](https://github.com/SparkPost/node-sparkpost/pull/169) Refactored templates library (@aydrian)
+- [#168](https://github.com/SparkPost/node-sparkpost/pull/168) Refactored suppression list library (@aydrian)
+- [#167](https://github.com/SparkPost/node-sparkpost/pull/167) Refactored sending domains library (@aydrian)
+- [#166](https://github.com/SparkPost/node-sparkpost/pull/166) Refactored recipient lists library (@aydrian)
+- [#163](https://github.com/SparkPost/node-sparkpost/pull/163) Set options.json=true for GET requests (@aydrian)
+- [#162](https://github.com/SparkPost/node-sparkpost/pull/162) Removed SendGrid Compatibility (@aydrian)
+- [#160](https://github.com/SparkPost/node-sparkpost/pull/160) Switch to using npm scripts instead of grunt (@aydrian)
+- [#159](https://github.com/SparkPost/node-sparkpost/pull/159) Switched JSHint for ESLint with SparkPost config (@aydrian)
+- [#158](https://github.com/SparkPost/node-sparkpost/pull/158) Refactored transmissions library (@aydrian)
+- [#157](https://github.com/SparkPost/node-sparkpost/pull/157) Removed support for nodejs versions .10 & .12 (@aydrian)
+- [#154](https://github.com/SparkPost/node-sparkpost/pull/154) Implement promise support (@aydrian)
+- [#123](https://github.com/SparkPost/node-sparkpost/pull/123) Added json flag to base request and tests to check for JSON response (@aydrian)
+- [#112](https://github.com/SparkPost/node-sparkpost/pull/112) Returns body.results or body as a response. Added debug support. (@aydrian)
+
 ## [1.3.8] - 2016-08-26
 - [#165](https://github.com/SparkPost/node-sparkpost/pull/165) Updated webhook update method to not send id in request (@aydrian)
 
@@ -110,7 +135,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## 0.1.0 - 2014-11-10
 - First Release!
 
-[unreleased]: https://github.com/sparkpost/node-sparkpost/compare/1.3.8...HEAD
+[unreleased]: https://github.com/sparkpost/node-sparkpost/compare/2.0.0...HEAD
+[2.0.0]: https://github.com/sparkpost/node-sparkpost/compare/1.3.8...2.0.0
 [1.3.8]: https://github.com/sparkpost/node-sparkpost/compare/1.3.7...1.3.8
 [1.3.7]: https://github.com/sparkpost/node-sparkpost/compare/1.3.6...1.3.7
 [1.3.6]: https://github.com/sparkpost/node-sparkpost/compare/1.3.5...1.3.6

CONTRIBUTING.md

@@ -13,6 +13,24 @@ Current milestone Pull Requests will receive priority review for merging.
 3. Write corresponding tests and code (only what is needed to satisfy the issue and tests please)
     * Include your tests in the 'test' directory in an appropriate test file
     * Write code to satisfy the tests
-    * Run tests using ```grunt test```
+    * Run tests using ```npm test```
 5. Ensure automated tests pass
-6. Submit a new Pull Request applying your feature/fix branch to the develop branch of the SparkPost SDK
+6. Submit a new Pull Request applying your feature/fix branch to the develop branch of the SparkPost client library
+
+## Releases
+If you are a collaborator, when you want release a new version, follow these steps.
+
+1. Make sure all the changes are merged into master
+2. Make sure all changes have passed [Travis CI build][1]
+3. Determine type of release. We use [Semantic Versioning](http://semver.org/).
+4. Update [CHANGELOG.md](CHANGELOG.md) with release notes and commit
+5. Run `npm version` command to increment `package.json` version, commit changes, tag changes, and push to upstream.
+    - Patch -> `npm version patch`
+    - Minor -> `npm version minor`
+    - Major -> `npm version major`
+6. Once [Travis CI build][1] (from tag) has completed, make sure you're working directory is clean and run `npm publish`
+   while in the project root.
+7. Create a new [Github Release](https://github.com/SparkPost/node-sparkpost/releases) using the new tag. Copy release
+   notes from the [CHANGELOG.md](CHANGELOG.md).
+
+[1]: https://travis-ci.org/SparkPost/node-sparkpost

README.md

@@ -1,6 +1,6 @@
 <a href="https://www.sparkpost.com"><img src="https://www.sparkpost.com/sites/default/files/attachments/SparkPost_Logo_2-Color_Gray-Orange_RGB.svg" width="200px"/></a>
 
-[Sign up](https://app.sparkpost.com/sign-up?src=Dev-Website&sfdcid=70160000000pqBb) for a SparkPost account and visit our [Developer Hub](https://developers.sparkpost.com) for even more content.
+[Sign up][sparkpost sign up] for a SparkPost account and visit our [Developer Hub](https://developers.sparkpost.com) for even more content.
 
 # Node.js Client Library
 
@@ -12,7 +12,7 @@ The official Node.js binding for your favorite [SparkPost APIs](https://develope
 
 Before using this library, you must have:
 
-* A shiny new SparkPost Account, [sign up for a new account](https://app.sparkpost.com/#/sign-up) or [login to SparkPost](https://app.sparkpost.com/)
+* A shiny new SparkPost Account, [sign up for a new account][sparkpost sign up] or [login to SparkPost](https://app.sparkpost.com/)
 * A valid SparkPost API Key. Check out our [Support Center](https://support.sparkpost.com/) for information on how to [create API keys](https://support.sparkpost.com/customer/portal/articles/1933377-create-api-keys)
 
 ## Installation
@@ -21,8 +21,10 @@ Before using this library, you must have:
 npm install sparkpost
 ```
 
+*Note: Node.js versions 0.10 and 0.12 are no longer supported. For versions < 4, please continue using [sparkpost v1.3.8](https://github.com/SparkPost/node-sparkpost/tree/1.3.8)* 
+
 ## Initialization
-**new SparkPost(apiKey, options)** - Initialization
+**new SparkPost(apiKey[, options])** - Initialization
 
 * `apiKey`
     * Required: yes (unless key is stored in `SPARKPOST_API_KEY` environment variable)
@@ -40,19 +42,23 @@ npm install sparkpost
     * Required: no
     * Type: `Object`
     * set headers that apply to all requests
+* `options.debug`
+    * Required: no
+    * Type: `Boolean`
+    * Default: `false`
+    * appends full response from request client as `debug` when `true` for debugging purposes<br/>
+    *Note: This will expose your api key to the client-side. Do not use in production.*
 
 ## Methods
-* **request(options, callback)**
+
+*Note: All methods return promises and accept an optional last argument callback. [Read about how we handle callbacks and promises](/docs/async.md).*
+
+* **request(options[, callback])**
     * `options` - [see request modules options](https://github.com/mikeal/request#requestoptions-callback)
     * `options.uri` - can either be a full url or a path that is appended to `options.origin` used at initialization ([url.resolve](http://nodejs.org/api/url.html#url_url_resolve_from_to))
-    * `callback` - executed after task is completed. **required**
-      * standard `callback(err, data)`
-      * `err` - any error that occurred
-      * `data.res` - full response from request client
-      * `data.body` - payload from response
-* **get | post | put | delete(options, callback)**
+    * `options.debug` - setting to `true` includes full response from request client for debugging purposes
+* **get | post | put | delete(options[, callback])**
     * `options` - see request options
-    * `callback` - see request options
     * Request method will be overwritten and set to the same value as the name of these methods.
 
 ## Creating a SparkPost Client
@@ -91,25 +97,27 @@ var options = {
   uri: 'metrics/domains'
 };
 
-client.get(options, function(err, data) {
-  if(err) {
+client.get(options)
+  .then(data => {
+    console.log(data);
+  })
+  .catch(err => {
     console.log(err);
-    return;
-  }
-
-  console.log(data.body);
-});
+  });
 ```
 
 ## Send An Email "Hello World" Example
-Below is an example of how to send a simple email. Sending an email is known as a *transmission*. By using the send method on the transmissions service that's available from the SparkPost object you instatiate you can pass in a *transmissionBody* object with all the information relevant to the email being sent. The send method also takes a callback method that will let you know if the email was sent successful and if not information about the error that ocurred.
+Below is an example of how to send a simple email. Sending an email is known as a *transmission*. By using the send 
+method on the transmissions service that's available from the SparkPost object you instantiate, you can pass in an 
+object with all the [transmission attributes](https://developers.sparkpost.com/api/transmissions#header-transmission-attributes) 
+relevant to the email being sent. The send method will return a promise that will let you know if the email was sent 
+successful and if not information about the error that occurred. If a callback is passed, it will be executed.
 
 ```javascript
 var SparkPost = require('sparkpost');
-var sp = new SparkPost('<YOUR API KEY>');
+var client = new SparkPost('<YOUR API KEY>');
 
-sp.transmissions.send({
-  transmissionBody: {
+client.transmissions.send({
     content: {
       from: 'testing@sparkpostbox.com',
       subject: 'Hello, World!',
@@ -118,15 +126,15 @@ sp.transmissions.send({
     recipients: [
       {address: '<YOUR EMAIL ADDRESS>'}
     ]
-  }
-}, function(err, res) {
-  if (err) {
+  })
+  .then(data => {
+    console.log('Woohoo! You just sent your first mailing!');
+    console.log(data);
+  })
+  .catch(err => {
     console.log('Whoops! Something went wrong');
     console.log(err);
-  } else {
-    console.log('Woohoo! You just sent your first mailing!');
-  }
-});
+  });
 ```
 
 ## SparkPost API Resources Supported in Node Client Library
@@ -147,20 +155,20 @@ Click on the desired API to see usage and more information
 ## Development
 
 ### Setup
-We use [Grunt](http://gruntjs.com/) for our task runner, so you will also have to install Grunt globally `npm install -g grunt-cli`
-
 Run `npm install` inside the repository to install all the dev dependencies.
 
 ### Testing
-Once all the dependencies are installed, you can execute the unit tests using `grunt test`
+Once all the dependencies are installed, you can execute the unit tests using `npm test`
 
 ### Contributing
-[Guidelines for adding issues](docs/ADDING_ISSUES.markdown)
+[Guidelines for adding issues](docs/ADDING_ISSUES.md)
 
-[Our coding standards](docs/CODE_STYLE_GUIDE.markdown)
+[Our coding standards](docs/CODE_STYLE_GUIDE.md)
 
 [Submitting pull requests](CONTRIBUTING.md)
 
 ### ChangeLog
 
 [See ChangeLog here](CHANGELOG.md)
+
+[sparkpost sign up]: https://app.sparkpost.com/sign-up?src=Dev-Website&sfdcid=701600000011daf

docs/async.md

@@ -0,0 +1,36 @@
+# Async Handling
+
+Callbacks and promises living together... MASS HYSTERIA. Or not! This library handles both of your favorite async strategies.
+
+### Promises
+
+All our library methods return promises, so if you're a promise-fan, just do what you normally do.
+
+```javascript
+let client = new SparkPost(key);
+
+client.templates.get(id)
+  .then((data) => {
+    // this the full API response body
+  })
+  .catch((err) => {
+    // handle the sad error
+  });
+```
+
+### Callbacks
+
+If you're more of a callbacker, that works too. Pass a callback as the last argument and it'll be handled like a regular, error-first callback.
+
+```javascript
+let client = new SparkPost(key);
+
+client.templates.get(id, (err, data) => {
+  if (err) {
+    // handle the sad error
+    return;
+  }
+
+  // this is the full API response body
+});
+```