Merge pull request #245 from gauntface/requestDetails

Request details

Author: marco-c

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
+);
+```
+
+The *getVapidHeaders()* method will take in the values needed to create
+an Authorization and Crypto-Key header.
+
+### 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:** When calling `generateRequestDetails()` the payload argument
+does not *need* to be defined, passing in null will return no body and
+> exclude any unnecessary headers.
+> Headers related to the GCM API Key and / or VAPID keys will be included
+> if supplied and required.
+
+### 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 containing 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/index.js

@@ -8,8 +8,10 @@ const webPush = new WebPushLib();
 
 module.exports = {
   encrypt: encryptionHelper.encrypt,
+  getVapidHeaders: vapidHelper.getVapidHeaders,
   generateVAPIDKeys: vapidHelper.generateVAPIDKeys,
   setGCMAPIKey: webPush.setGCMAPIKey,
   setVapidDetails: webPush.setVapidDetails,
+  generateRequestDetails: webPush.generateRequestDetails,
   sendNotification: webPush.sendNotification
 };

src/web-push-lib.js

@@ -66,38 +66,39 @@ WebPushLib.prototype.setVapidDetails =
     };
   };
 
-/**
- * To send a push notification call this method with a subscription, optional
- * payload and any options.
- * @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.
- */
-WebPushLib.prototype.sendNotification =
+  /**
+   * 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 {Object}                       This method returns an Object which
+   * contains 'endpoint', 'method', 'headers' and 'payload'.
+   */
+WebPushLib.prototype.generateRequestDetails =
   function(subscription, payload, options) {
     if (!subscription || !subscription.endpoint) {
-      return Promise.reject('You must pass in a subscription with at least ' +
+      throw new Error('You must pass in a subscription with at least ' +
         'an endpoint.');
     }
 
     if (typeof subscription.endpoint !== 'string' ||
       subscription.endpoint.length === 0) {
-      return Promise.reject('The subscription endpoint must be a string with ' +
+      throw new Error('The subscription endpoint must be a string with ' +
         'a valid URL.');
     }
 
     if (payload) {
       // Validate the subscription keys
       if (!subscription.keys || !subscription.keys.p256dh ||
         !subscription.keys.auth) {
-        return Promise.reject('To send a message with a payload, the ' +
+        throw new Error('To send a message with a payload, the ' +
           'subscription must have \'auth\' and \'p256dh\' keys.');
       }
     }
@@ -116,7 +117,7 @@ WebPushLib.prototype.sendNotification =
       for (let i = 0; i < optionKeys.length; i += 1) {
         const optionKey = optionKeys[i];
         if (validOptionKeys.indexOf(optionKey) === -1) {
-          return Promise.reject('\'' + optionKey + '\' is an invalid option. ' +
+          throw new Error('\'' + optionKey + '\' is an invalid option. ' +
             'The valid options are [\'' + validOptionKeys.join('\', \'') +
             '\'].');
         }
@@ -139,7 +140,7 @@ WebPushLib.prototype.sendNotification =
       timeToLive = DEFAULT_TTL;
     }
 
-    const requestOptions = {
+    const requestDetails = {
       method: 'POST',
       headers: {
         TTL: timeToLive
@@ -152,27 +153,23 @@ WebPushLib.prototype.sendNotification =
         typeof subscription !== 'object' ||
         !subscription.keys.p256dh ||
         !subscription.keys.auth) {
-        return Promise.reject(new Error('Unable to send a message with ' +
+        throw new Error(new Error('Unable to send a message with ' +
           'payload to this subscription since it doesn\'t have the ' +
           'required encryption keys'));
       }
 
-      try {
-        const encrypted = encryptionHelper.encrypt(
-          subscription.keys.p256dh, subscription.keys.auth, payload);
+      const encrypted = encryptionHelper.encrypt(
+        subscription.keys.p256dh, subscription.keys.auth, payload);
 
-        requestOptions.headers['Content-Length'] = encrypted.cipherText.length;
-        requestOptions.headers['Content-Type'] = 'application/octet-stream';
-        requestOptions.headers['Content-Encoding'] = 'aesgcm';
-        requestOptions.headers.Encryption = 'salt=' + encrypted.salt;
-        requestOptions.headers['Crypto-Key'] = 'dh=' + urlBase64.encode(encrypted.localPublicKey);
+      requestDetails.headers['Content-Length'] = encrypted.cipherText.length;
+      requestDetails.headers['Content-Type'] = 'application/octet-stream';
+      requestDetails.headers['Content-Encoding'] = 'aesgcm';
+      requestDetails.headers.Encryption = 'salt=' + encrypted.salt;
+      requestDetails.headers['Crypto-Key'] = 'dh=' + urlBase64.encode(encrypted.localPublicKey);
 
-        requestPayload = encrypted.cipherText;
-      } catch (err) {
-        return Promise.reject(err);
-      }
+      requestPayload = encrypted.cipherText;
     } else {
-      requestOptions.headers['Content-Length'] = 0;
+      requestDetails.headers['Content-Length'] = 0;
     }
 
     const isGCM = subscription.endpoint.indexOf(
@@ -183,7 +180,7 @@ WebPushLib.prototype.sendNotification =
         console.warn('Attempt to send push notification to GCM endpoint, ' +
           'but no GCM key is defined'.bold.red);
       } else {
-        requestOptions.headers.Authorization = 'key=' + currentGCMAPIKey;
+        requestDetails.headers.Authorization = 'key=' + currentGCMAPIKey;
       }
     } else if (currentVapidDetails) {
       const parsedUrl = url.parse(subscription.endpoint);
@@ -197,22 +194,56 @@ WebPushLib.prototype.sendNotification =
         currentVapidDetails.privateKey
       );
 
-      requestOptions.headers.Authorization = vapidHeaders.Authorization;
-      if (requestOptions.headers['Crypto-Key']) {
-        requestOptions.headers['Crypto-Key'] += ';' +
+      requestDetails.headers.Authorization = vapidHeaders.Authorization;
+      if (requestDetails.headers['Crypto-Key']) {
+        requestDetails.headers['Crypto-Key'] += ';' +
           vapidHeaders['Crypto-Key'];
       } else {
-        requestOptions.headers['Crypto-Key'] = vapidHeaders['Crypto-Key'];
+        requestDetails.headers['Crypto-Key'] = vapidHeaders['Crypto-Key'];
       }
     }
 
+    requestDetails.body = requestPayload;
+    requestDetails.endpoint = subscription.endpoint;
+
+    return requestDetails;
+  };
+
+/**
+ * To send a push notification call this method with a subscription, optional
+ * payload and any options.
+ * @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.
+ */
+WebPushLib.prototype.sendNotification =
+  function(subscription, payload, options) {
+    let requestDetails;
+    try {
+      requestDetails = this.generateRequestDetails(
+        subscription, payload, options);
+    } catch (err) {
+      return Promise.reject(err);
+    }
+
     return new Promise(function(resolve, reject) {
-      const urlParts = url.parse(subscription.endpoint);
-      requestOptions.hostname = urlParts.hostname;
-      requestOptions.port = urlParts.port;
-      requestOptions.path = urlParts.path;
+      const httpsOptions = {};
+      const urlParts = url.parse(requestDetails.endpoint);
+      httpsOptions.hostname = urlParts.hostname;
+      httpsOptions.port = urlParts.port;
+      httpsOptions.path = urlParts.path;
+
+      httpsOptions.headers = requestDetails.headers;
+      httpsOptions.method = requestDetails.method;
 
-      const pushRequest = https.request(requestOptions, function(pushResponse) {
+      const pushRequest = https.request(httpsOptions, function(pushResponse) {
         let responseText = '';
 
         pushResponse.on('data', function(chunk) {
@@ -237,8 +268,8 @@ WebPushLib.prototype.sendNotification =
         reject(e);
       });
 
-      if (requestPayload) {
-        pushRequest.write(requestPayload);
+      if (requestDetails.body) {
+        pushRequest.write(requestDetails.body);
       }
 
       pushRequest.end();