notifications-node-client - npm Package Compare versions

Comparing version 4.3.0 to 4.4.0

.github/PULL_REQUEST_TEMPLATE.md

@@ -13,2 +13,3 @@ <!--Thanks for contributing to GOV.UK Notify. Using this template to write your pull request message will help get it merged as soon as possible. -->
   - `README.md`
+  - `DOCUMENTATION.md`
   - `CHANGELOG.md`
@@ -15,0 +16,0 @@ - [ ] I’ve bumped the version number in

CHANGELOG.md

@@ -0,1 +1,8 @@
+## [4.4.0] - 2018-09-05
+
+### Changed
+
+* Added instructions for uploading a document to be linked to from an email notification.
+    * Created a helper function `prepareUpload` as a part of this development. This function encodes the document that is to be uploaded with base64 and returns a dictionary with prepared document as a value (the way our API is prepared to receive it). It also checks if the provided file is not larger than 2MB. The function throws an error if the file is too big.
+
 ## [4.3.0] - 2018-09-04
@@ -55,3 +62,3 @@
     * `setProxy(proxyUrl)` - specify the URL of a proxy for the client to use (optional)
-    
+
 ## [3.1.0] - 2017-05-10
@@ -58,0 +65,0 @@

client/notification.js

@@ -294,3 +294,8 @@ var ApiClient = require('./api_client'),
     this.apiClient.setProxy(url);
-  }
+  },
+
+  prepareUpload: function(pdf_data) {
+    if (pdf_data.length > 2 * 1024 * 1024) { throw "Document is larger than 2MB."; }
+    return {'file': pdf_data.toString('base64')}
+  },
 });
@@ -297,0 +302,0 @@

DOCUMENTATION.md

@@ -253,3 +253,77 @@ # GOV.UK Notify Node.js client
 
+### Send a document by email
+Send files without the need for email attachments.
 
+To send a document by email, add a placeholder field to the template then upload a file. The placeholder field will contain a secure link to download the document.
+
+[Contact the GOV.UK Notify team](https://www.notifications.service.gov.uk/support) to enable this function for your service.
+
+#### Add a placeholder field to the template
+
+In Notify, use double brackets to add a placeholder field to the email template. For example:
+
+"Download your document at: ((link_to_document))"
+
+
+#### Upload your document
+˜
+The document you upload must be a PDF file smaller than 2MB.
+
+Pass the file object as a value into the personalisation argument. For example:
+
+```javascript
+var fs = require('fs');
+
+fs.readFile('path/to/document.pdf', function(err, document) {
+	console.log(err);
+	notifyClient.sendEmail(templateId, emailAddress, {
+    personalisation: {
+        first_name: 'Amala',
+        application_date: '2018-01-01',
+        link_to_document: notifyClient.prepareUpload(document)
+    }
+	}).then(response => console.log(response.body)).catch(err => console.error(err))
+});
+```
+
+#### Response
+
+If the request to the client is successful, the client returns a response `object`, with a following `body` attribute:
+
+```javascript
+{
+  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
+  "reference": "STRING",
+  "content": {
+    "subject": "SUBJECT TEXT",
+    "body": "MESSAGE TEXT",
+    "from_email": "SENDER EMAIL"
+  },
+  "uri": "https://api.notifications.service.gov.uk/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
+  "template": {
+    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
+    "version": INTEGER,
+    "uri": "https://api.notifications.service.gov.uk/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a"
+  }
+}
+```
+
+#### Error codes
+
+If the request is not successful, the client returns an error `error object`:
+
+|error.status_code|error.message|How to fix|
+|:---|:---|:---|
+|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can't send to this recipient using a team-only API key"`<br>`]}`|Use the correct type of [API key](#api-keys)|
+|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can't send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"`<br>`}]`|Your service cannot send this notification in [trial mode](https://www.notifications.service.gov.uk/features/using-notify#trial-mode)|
+|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Unsupported document type '{}'. Supported types are: {}"`<br>`}]`|The document you upload must be a PDF file|
+|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Document didn't pass the virus scan"`<br>`}]`|The document you upload must be virus free|
+|`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Error: Your system clock must be accurate to within 30 seconds"`<br>`}]`|Check your system clock|
+|`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Invalid token: signature, api token not found"`<br>`}]`|Use the correct type of [API key](#api-keys)|
+|`429`|`[{`<br>`"error": "RateLimitError",`<br>`"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds"`<br>`}]`|Refer to [API rate limits](#api-rate-limits) for more information|
+|`429`|`[{`<br>`"error": "TooManyRequestsError",`<br>`"message": "Exceeded send limits (LIMIT NUMBER) for today"`<br>`}]`|Refer to [service limits](#service-limits) for the limit number|
+|`500`|`[{`<br>`"error": "Exception",`<br>`"message": "Internal server error"`<br>`}]`|Notify was unable to process the request, resend your notification.|
+|`N/A`|`[{`<br>`"error": "Exception",`<br>`"message": "Document is larger than 2MB."`<br>`}]`|The file you tried to upload was above the 2MB limit. Send a file that weighs less than 2MB.|
+
+
 ### Letter
@@ -256,0 +330,0 @@

package.json

 {
   "name": "notifications-node-client",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "GOV.UK Notify Node.js client ",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

@@ -253,3 +253,76 @@ # GOV.UK Notify Node.js client
 
+### Send a document by email
+Send files without the need for email attachments.
 
+To send a document by email, add a placeholder field to the template then upload a file. The placeholder field will contain a secure link to download the document.
+
+[Contact the GOV.UK Notify team](https://www.notifications.service.gov.uk/support) to enable this function for your service.
+
+#### Add a placeholder field to the template
+
+In Notify, use double brackets to add a placeholder field to the email template. For example:
+
+"Download your document at: ((link_to_document))"
+
+#### Upload your document
+˜
+The document you upload must be a PDF file smaller than 2MB.
+
+Pass the file object as a value into the personalisation argument. For example:
+
+```javascript
+var fs = require('fs');
+
+fs.readFile('path/to/document.pdf', function(err, document) {
+	console.log(err);
+	notifyClient.sendEmail(templateId, emailAddress, {
+    personalisation: {
+        first_name: 'Amala',
+        application_date: '2018-01-01',
+        link_to_document: notifyClient.prepareUpload(document)
+    }
+	}).then(response => console.log(response.body)).catch(err => console.error(err))
+});
+```
+
+#### Response
+
+If the request to the client is successful, the client returns a response `object`, with a following `body` attribute:
+
+```javascript
+{
+  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
+  "reference": "STRING",
+  "content": {
+    "subject": "SUBJECT TEXT",
+    "body": "MESSAGE TEXT",
+    "from_email": "SENDER EMAIL"
+  },
+  "uri": "https://api.notifications.service.gov.uk/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
+  "template": {
+    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
+    "version": INTEGER,
+    "uri": "https://api.notifications.service.gov.uk/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a"
+  }
+}
+```
+
+#### Error codes
+
+If the request is not successful, the client returns an error `error object`:
+
+|error.status_code|error.message|How to fix|
+|:---|:---|:---|
+|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can't send to this recipient using a team-only API key"`<br>`]}`|Use the correct type of [API key](#api-keys)|
+|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can't send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"`<br>`}]`|Your service cannot send this notification in [trial mode](https://www.notifications.service.gov.uk/features/using-notify#trial-mode)|
+|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Unsupported document type '{}'. Supported types are: {}"`<br>`}]`|The document you upload must be a PDF file|
+|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Document didn't pass the virus scan"`<br>`}]`|The document you upload must be virus free|
+|`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Error: Your system clock must be accurate to within 30 seconds"`<br>`}]`|Check your system clock|
+|`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Invalid token: signature, api token not found"`<br>`}]`|Use the correct type of [API key](#api-keys)|
+|`429`|`[{`<br>`"error": "RateLimitError",`<br>`"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds"`<br>`}]`|Refer to [API rate limits](#api-rate-limits) for more information|
+|`429`|`[{`<br>`"error": "TooManyRequestsError",`<br>`"message": "Exceeded send limits (LIMIT NUMBER) for today"`<br>`}]`|Refer to [service limits](#service-limits) for the limit number|
+|`500`|`[{`<br>`"error": "Exception",`<br>`"message": "Internal server error"`<br>`}]`|Notify was unable to process the request, resend your notification.|
+|`N/A`|`[{`<br>`"error": "Exception",`<br>`"message": "Document is larger than 2MB."`<br>`}]`|The file you tried to upload was above the 2MB limit. Send a file that weighs less than 2MB.|
+
+
 ### Letter
@@ -256,0 +329,0 @@

spec/integration/test.js

@@ -94,2 +94,18 @@ const NotifyClient = require('../../client/notification.js').NotifyClient;
 
+    it('sends email notification with document upload', () => {
+      var postEmailNotificationResponseJson = require('./schemas/v2/POST_notification_email_response.json'),
+        options = {personalisation: { name: 'Foo', documents:
+          notifyClient.prepareUpload(Buffer.from("%PDF-1.5 testpdf"))
+        }, reference: clientRef};
+
+      return notifyClient.sendEmail(emailTemplateId, email, options).then((response) => {
+        response.statusCode.should.equal(201);
+        expect(response.body).to.be.jsonSchema(postEmailNotificationResponseJson);
+        response.body.content.body.should.equal('Hello Foo\r\n\r\nFunctional test help make our world a better place');
+        response.body.content.subject.should.equal('Functional Tests are good');
+        response.body.reference.should.equal(clientRef);
+        emailNotificationId = response.body.id;
+      })
+    });
+
     it('send sms notification', () => {
@@ -96,0 +112,0 @@ var postSmsNotificationResponseJson = require('./schemas/v2/POST_notification_sms_response.json'),

spec/notification.js

@@ -89,3 +89,29 @@ let expect = require('chai').expect,
       });
+    });
 
+    it('should send an email with document upload', () => {
+
+      let email = '[e-mail]',
+        templateId = '123',
+        options = {
+          personalisation: {documents:
+            notifyClient.prepareUpload(Buffer.from("%PDF-1.5 testpdf"))
+          },
+          emailReplyToId: '456',
+        },
+        data = {
+          template_id: templateId,
+          email_address: email,
+          personalisation: options.personalisation,
+          email_reply_to_id: options.emailReplyToId
+        };
+
+      notifyAuthNock
+      .post('/v2/notifications/email', data)
+      .reply(200, {hooray: 'bkbbk'});
+
+      return notifyClient.sendEmail(templateId, email, options)
+      .then((response) => {
+        expect(response.statusCode).to.equal(200);
+      });
     });
@@ -107,2 +133,12 @@
 
+  describe('prepareUpload', () => {
+    it('should throw error when file bigger than 2MB is supplied', () => {
+
+      let file = Buffer.alloc(3*1024*1024)
+      expect(function(){
+        notifyClient.prepareUpload(file);
+      }).to.throw("Document is larger than 2MB.")
+    });
+  });
+
   describe('sendSms', () => {
@@ -109,0 +145,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

125244

increased by8.99%

Lines of code

1786

increased by2.82%

Number of lines in readme file

1028

increased by7.64%

No dependency changes