Improvements and notifications on all hooks

README.md

@@ -1,15 +1,15 @@
 # ember-cli-deploy-notifications [![Build Status](https://travis-ci.org/simplabs/ember-cli-deploy-notifications.svg)](https://travis-ci.org/simplabs/ember-cli-deploy-notifications)
 
 > An ember-cli-deploy plugin to notify external services (e.g. an error
-> tracking service) of a successful deployment.
+> tracking service) of successful hook executions in your deploy pipeline.
 
 [![](https://ember-cli-deploy.github.io/ember-cli-deploy-version-badges/plugins/ember-cli-deploy-notifications.svg)](http://ember-cli-deploy.github.io/ember-cli-deploy-version-badges/)
 
 ## What is an ember-cli-deploy plugin?
 
 A plugin is an addon that can be executed as a part of the ember-cli-deploy pipeline. A plugin will implement one or more of the ember-cli-deploy's pipeline hooks.
 
-For more information on what plugins are and how they work, please refer to the [Plugin Documentation][2].
+For more information on what plugins are and how they work, please refer to the [Plugin Documentation][1].
 
 ## Quick Start
 
@@ -28,12 +28,17 @@ ENV.notifications = {
   services: {
     "<some-key>": {
       url: <service-url>,
-      data: function(context) {
-        // return any object that should be passed as data here
+      headers: {
+        // custom headers go here
+      },
+      method: '<http-method>', // defaults to 'POST'
+      body: function(/*context*/) {
+        // return any object that should be passed as request body here
         return {
           apiKey: <your-api-key>
         };
       }
+      didActivate: true
     }
   }
 }
@@ -47,84 +52,310 @@ $ ember deploy
 
 ## ember-cli-deploy Hooks Implemented
 
-For detailed information on what plugin hooks are and how they work, please refer to the [Plugin Documentation][2].
+For detailed information on what plugin hooks are and how they work, please refer to the [Plugin Documentation][1].
 
 - `configure`
+- `setup`
+
+_Hooks that can be used for notifications:_
+
+- `willDeploy`
+- `willBuild`
+- `build`
+- `didBuild`
+- `willPrepare`
+- `prepare`
+- `didPrepare`
+- `willUpload`
+- `upload`
+- `didUpload`
+- `willActivate`
+- `activate`
 - `didActivate`
+- `teardown`
+- `fetchRevisions`
+- `displayRevisions`
+- `didFail`
 
 ## Configuration Options
 
-For detailed information on how configuration of plugins works, please refer to the [Plugin Documentation][2].
+For detailed information on how configuration of plugins works, please refer to the [Plugin Documentation][1].
 
 ###services
 
-An object that identifies all webhooks you want to notify of a successful deployment. You will put a key for every service you want to call after a successful deploy here.
+An object that identifies all webhooks you want to notify. You will put a key for every service you want to call on deploy here.
+
+A `service` configuration needs to provide four properties as configuration for
+`ember-cli-deploy-notifications` to know how to notify the service correctly:
+
+- `url` The url to call
+- `method` The HTTP-method to use for the call (defaults to `'POST'`)
+- `headers` A property to specify custom HTTP-headers (defaults to `{}`)
+- `body` The body of the request
+
+<hr/>
+**Whenever one of these properties returns a _falsy_ value, the service will _not_ be
+called.**
+<hr/>
+
+All these properties can return a value directly or can be implemented as
+a function which returns the value for this property and gets called with the
+deployment context. The `this` scope will be set to the service config object
+itself.
+
+*Example:*
+
+```javascript
+ENV.notifications = {
+  services: {
+    slack: {
+      webhookURL: '<your-webhook-url>',
+      url: function() {
+        return this.webhookURL;
+      },
+      method: 'POST',
+      headers: {},
+      body: function(context) {
+        var deployer = context.deployer;
+
+        return {
+          text: deployer + ' deployed a new revision'
+        }
+      }
+    }
+  }
+};
+```
+
+Additionally you have to specify on which hook to notify the service in the
+deploy pipeline. To do this you can simply pass a truthy value as a property
+named the same as the hook at which you want to notify the service. This can
+als be used to override the defaults that you specify on a service.
+
+*Example:*
+
+```javascript
+  ENV.notifications = {
+    services: {
+      slack: {
+        url: 'your-webhook-url',
+        method: 'POST',
+        headers: {},
+        body: {
+          text: 'A new revision was activated!'
+        },
+        didActivate: true
+        didDeploy: {
+          body: {
+            text: 'Deployment successful!'
+          }
+        },
+        didFail: {
+          body: {
+            text: 'Deployment failed!'
+          }
+        }
+      }
+    }
+  };
+```
 
 There are two types of services you can specify in the `services` property:
 
 a)  __preconfigured services__
 
-Preconfigured services don't need to be passed a `url`-property as `ember-cli-deploy-notifications` already knows about the url it needs to call when notifying the service. You only need to pass a `data`-function as configuration property to these services.
+Preconfigured services only need to be passed service specific configuration
+options. This depends on the service (see below) but you can also provide all
+other service configuration properties that were explained before to override
+the defaults.
 
 *Example:*
 
 ```javascript
 ENV.notifications = {
   services: {
     bugsnag: {
-      data: function(context) {
+      url: 'https://bugsnag.simplabs.com/deploy',
+      apiKey: '1234',
+      didActivate: true
+    }
+  }
+};
+```
+
+Preconfigured services aren't very special but maintainers and contributors
+have already provided a base configuration that can be overridden by the
+plugin users. This for example is basically the default implementation that is
+already configured for the slack service:
+
+```javascript
+  ENV.notifications.services = {
+    // ...
+    slack: {
+      url: function() {
+        return this.webhookURL;
+      },
+      method: 'POST',
+      headers: {}
+    }
+  };
+```
+
+Users then only have to provide `webhookURL` and a `body`-property for the
+hooks that should send a message to slack.
+
+*Example:*
+
+```javascript
+  ENV.notifications.services = {
+    slack: {
+      webhookURL: '<your-slack-webhook-url>',
+      didActivate: {
+        body: {
+          text: 'A new revision was activated!'
+        }
+      }
+    }
+  };
+```
+
+Currently available preconfigured services are:
+
+- `bugsnag` [An error-tracking service](https://bugsnag.com)
+- `slack` [The popular messaging app](https://slack.com/)
+
+####bugsnag
+
+To configure bugsnag you need to at least provide an `apiKey` and specify
+a hook on which bugsnag should be notified of a deployment. You'll most likely
+want to notify bugsnag of a deployment in the `didActivate`-hook as this is the
+hook that actually makes a new version of your app available to your users.
+
+*Example:*
+
+```javascript
+  ENV.notifications.services = {
+    bugsnag: {
+      apiKey: '<your-api-key>',
+      didActivate: true
+    }
+  };
+```
+
+__Required configuration__
+
+- `apiKey` The api-key to send as part of the request payload (identifies the
+  application)
+
+__Default configuration__
+
+```
+  ENV.notifications.services = {
+    bugsnag: {
+      url: 'http://notify.bugsnag.com/deploy',
+      method: 'POST',
+      headers: {},
+      body: function() {
+        var apiKey = this.apiKey;
+
+        if (!apiKey) { return; }
+
         return {
-          apiKey: '<your-api-key'
+          apiKey: this.apiKey,
+          releaseStage: process.env.DEPLOY_TARGET
         }
       }
     }
   }
-};
 ```
 
-Currently available preconfigured services are:
+####slack
+
+*Example:*
+
+```javascript
+  ENV.notifications.services = {
+    slack: {
+      webhookURL: '<your-slack-webhook-url>',
+      didActivate: {
+        body: {
+          text: 'A new revision was activated!'
+        }
+      }
+    }
+  };
+```
+
+__Required configuration__
+
+- `webhookURL` The [incoming webhook's](https://api.slack.com/incoming-webhooks)-url that should be called.
 
-- `bugsnag`
+- `body` You need to provide a payload that gets send to slack. Please refer to
+  the [documentation](https://api.slack.com/incoming-webhooks) on how message
+payloads can be used to customize the appearance of a message in slack. At
+least you have to provide a `text` property in the payload.
 
-If you want to provide a custom url for preconfigured services you can though and `ember-cli-deploy-notifications` will notify the custom url instead.
+__Default configuration__
+
+```javascript
+  ENV.notifications.services = {
+    // ...
+    slack: {
+      url: function() {
+        return this.webhookURL;
+      },
+      method: 'POST',
+      headers: {}
+    }
+  };
+```
 
 b) __custom services__
 
-Custom services need to be configured with a `url`-property and a `data`-function.
+Custom services need to be configured with a `url` and `body` property.
+`headers` will default to `{}` and `method` will default to `'POST'`. All these
+options can be overridden as described before of course.
 
 *Example:*
 
 ```javascript
 ENV.notifications = {
   services: {
-    bugsnag: {
-      data: function() {
-        return { apiKey: '1234' }
-      }
-    },
     simplabs: {
       url: 'https://notify.simplabs.com/deploy',
-      data: function(context) {
+      body: function(context) {
         var deployer = context.deployer;
-        
+
         return {
           secret: 'supersecret',
           deployer: deployer
         }
-      }
+      },
+      didActivate: true
+    },
+    newRelic: {
+      url: 'https://api.newrelic.com/deployments.json',
+      headers: {
+        "api-key": "<your-api-key>"
+      },
+      method: 'POST',
+      body: {
+        deployment: {
+          // ...
+        }
+      },
+      didDeploy: true
     }
   }
-}
+};
 ```
 
-As you can see in the last example the data function will be passed the current deploy context which can then be used to send data to services based on the current deploy.
-
 ###httpClient
 
-The underlying http-library used to send POST-requests to the specified services. This allows users to customize the library that's used for http requests which is useful in tests but might be useful to some users as well. By default the plugin uses [request](https://github.com/request/request).
+The underlying http-library used to send requests to the specified services. This allows users to customize the library that's used for http requests which is useful in tests but might be useful to some users as well. By default the plugin uses [request](https://github.com/request/request).
 
 ## Running Tests
 
 - `npm test`
 
-[2]: http://ember-cli.github.io/ember-cli-deploy/plugins "Plugin Documentation"
+[1]: http://ember-cli.github.io/ember-cli-deploy/plugins "Plugin Documentation"