adding some simple tests

Author: Matt Gaunt

README.md

@@ -276,6 +276,131 @@ encryption.
 - *salt*: A string representing the salt used to encrypt the payload.
 - *cipherText*: The encrypted payload as a Buffer.
 
+<hr />
+
+## getVapidHeaders(audience, subject, publicKey, privateKey, expiration)
+
+```javascript
+const parsedUrl = url.parse(subscription.endpoint);
+const audience = parsedUrl.protocol + '//' +
+  parsedUrl.hostname;
+
+const vapidHeaders = vapidHelper.getVapidHeaders(
+  audience,
+  'mailto: [email protected]',
+  vapidDetails.publicKey,
+  vapidDetails.privateKey
+);
+```
+
+Encrypts the payload according to the [Message Encryption for Web
+Push](https://webpush-wg.github.io/webpush-encryption/) standard.
+
+> (*sendNotification* will automatically encrypt the payload for you, so if
+> you use *sendNotification* you don't need to worry about it).
+
+### Input
+
+The `getVapidHeaders()` method expects the following input:
+
+- *audience*: the origin of the **push service**.
+- *subject*: the mailto or URL for your application.
+- *publicKey*: the VAPID public key.
+- *privateKey*: the VAPID private key.
+
+### Returns
+
+This method returns an object with the following fields:
+
+- *localPublicKey*: The public key matched the private key used during
+encryption.
+- *salt*: A string representing the salt used to encrypt the payload.
+- *cipherText*: The encrypted payload as a Buffer.
+
+<hr />
+
+## generateRequestDetails(pushSubscription, payload, options)
+
+```javascript
+const pushSubscription = {
+  endpoint: '< Push Subscription URL >';
+  keys: {
+    p256dh: '< User Public Encryption Key >',
+    auth: '< User Auth Secret >'
+  }
+};
+
+const payload = '< Push Payload String >';
+
+const options = {
+  gcmAPIKey: '< GCM API Key >',
+  vapidDetails: {
+    subject: '< \'mailto\' Address or URL >',
+    publicKey: '< URL Safe Base64 Encoded Public Key >',
+    privateKey: '< URL Safe Base64 Encoded Private Key >',
+  }
+  TTL: <Number>
+}
+
+try {
+  const details = webpush.generateRequestDetails(
+    pushSubscription,
+    payload,
+    options
+  );
+} catch (err) {
+  console.error(err);
+}
+```
+
+> **Note:** `generateRequestDetails()` you don't need to define a payload,
+and this method will return details without a GCM API Key and / or VAPID keys.
+
+### Input
+
+**Push Subscription**
+
+The first argument must be an object containing the details for a push
+subscription.
+
+The expected format is the same output as JSON.stringify'ing a PushSubscription
+in the browser.
+
+**Payload**
+
+The payload is optional, but if set, will be encrypted and a [*Buffer*](https://nodejs.org/api/buffer.html)
+ will be returned via the `payload` parameter.
+
+This argument must be either a *string* or a node
+[*Buffer*](https://nodejs.org/api/buffer.html).
+
+> **Note:** In order to encrypt the *payload*, the *pushSubscription* **must**
+have a *keys* object with *p256dh* and *auth* values.
+
+**Options**
+
+Options is an optional argument that if defined should be an object containing
+any of the following values defined, although none of them are required.
+
+- **gcmAPIKey** can be a GCM API key to be used for this request and this
+request only. This overrides any API key set via `setGCMAPIKey()`.
+- **vapidDetails** should be an object with *subject*, *publicKey* and
+*privateKey* values defined. These values should follow the [VAPID Spec](https://tools.ietf.org/html/draft-thomson-webpush-vapid).
+- **TTL** is a value in seconds that describes how long a push message is
+retained by the push service (by default, four weeks);
+
+### Returns
+
+An object contains all the details needed to make a network request, the
+object will contain:
+
+- *endpoint*, the URL to send the request to;
+- *method*, this will be 'POST';
+- *headers*, the headers to add to the request;
+- *body*, the body of the request (As a Node Buffer).
+
+<hr />
+
 # Browser Support
 
 <table>

src/web-push-lib.js

@@ -67,18 +67,19 @@ WebPushLib.prototype.setVapidDetails =
   };
 
   /**
-   * To send a push notification call this method with a subscription, optional
-   * payload and any options.
+   * To get the details of a request to trigger a push message, without sending
+   * a push notification call this method.
+   *
+   * This method will throw an error if there is an issue with the input.
    * @param  {PushSubscription} subscription The PushSubscription you wish to
    * send the notification to.
    * @param  {string} [payload]              The payload you wish to send to the
    * the user.
    * @param  {Object} [options]              Options for the GCM API key and
    * vapid keys can be passed in if they are unique for each notification you
    * wish to send.
-   * @return {Promise}                       This method returns a Promise which
-   * resolves if the sending of the notification was successful, otherwise it
-   * rejects.
+   * @return {Object}                       This method returns an Object which
+   * contains 'endpoint', 'method', 'headers' and 'payload'.
    */
 WebPushLib.prototype.generateRequestDetails =
   function(subscription, payload, options) {
@@ -203,7 +204,7 @@ WebPushLib.prototype.generateRequestDetails =
       }
     }
 
-    requestDetails.payload = requestPayload;
+    requestDetails.body = requestPayload;
     requestDetails.endpoint = subscription.endpoint;
 
     return requestDetails;
@@ -269,8 +270,8 @@ WebPushLib.prototype.sendNotification =
         reject(e);
       });
 
-      if (requestDetails.payload) {
-        pushRequest.write(requestDetails.payload);
+      if (requestDetails.body) {
+        pushRequest.write(requestDetails.body);
       }
 
       pushRequest.end();

test/test-vapid-helper.js

@@ -15,6 +15,7 @@ const VALID_EXPIRATION = Math.floor(Date.now() / 1000) + (60 * 60 * 12);
 suite('Test Vapid Helpers', function() {
   test('is defined', function() {
     assert(webPush.generateVAPIDKeys);
+    assert(webPush.getVapidHeaders);
   });
 
   test('generate vapid keys', function() {