notifications-node-client 5.1.2 → 5.2.1

package/CHANGELOG.md

@@ -1,6 +1,19 @@
+## 5.2.1 - 2022-10-19
+
+* Support strings in calls to `prepareUpload`. `fs.readFile` can return strings if an encoding is provided, and the client didn't handle these correctly.
+
+## 5.2.0 - 2022-09-27
+
+* Add support for new security features when sending a file by email:
+  * `confirmEmailBeforeDownload` can be set to `true` to require the user to enter their email address before accessing the file.
+  * `retentionPeriod` can be set to `<1-78> weeks` to set how long the file should be made available.
+
+* The `isCsv` parameter to `prepareUpload` has now been replaced by an `options` parameter. The implementation has been done in a backwards-compatible way, so if you are just sending `true/false` values as the seecond parameter, that will continue to work. Though we still recommend updating to use the new options format.
+
+
 ## 5.1.2 - 2022-09-23
 
-Remove underscore.js dependency
+Remove underscore.js dependencyr new send a file features)
 
 ## 5.1.1 - 2022-01-18
 

package/DOCUMENTATION.md

@@ -289,10 +289,17 @@ If the request is not successful, the promise fails with an `err`.
 
 To send a file by email, add a placeholder to the template then upload a file. The placeholder will contain a secure link to download the file.
 
-The file will be available for the recipient to download for 18 months.
-
 The links are unique and unguessable. GOV.UK Notify cannot access or decrypt your file.
 
+Your file will be available to download for a default period of 78 weeks (18 months). From 29 March 2023 we will reduce this to 26 weeks (6 months) for all new files. Files sent before 29 March will not be affected.
+
+To help protect your files you can also:
+
+* ask recipients to confirm their email address before downloading
+* choose the length of time that a file is available to download
+
+To turn these features on or off, you will need version 5.2.0 of the Node.js client library or a more recent version.
+
 #### Add contact details to the file download page
 
 1. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in).
@@ -305,9 +312,9 @@ The links are unique and unguessable. GOV.UK Notify cannot access or decrypt you
 1. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in).
 1. Go to the __Templates__ page and select the relevant email template.
 1. Select __Edit__.
-1. Add a placeholder to the email template using double brackets. For example:
+1. Add a placeholder to the email template using double brackets. For example: "Download your file at: ((link_to_file))"
 
-"Download your file at: ((link_to_file))"
+Your email should also tell recipients how long the file will be available to download.
 
 #### Upload your file
 
@@ -354,6 +361,91 @@ fs.readFile('path/to/document.csv', function (err, csvFile) {
 })
 ```
 
+#### Ask recipients to confirm their email address before they can download the file
+
+This new security feature is optional. You should use it if you send files that are sensitive - for example, because they contain personal information about your users.
+
+When a recipient clicks the link in the email you’ve sent them, they have to enter their email address. Only someone who knows the recipient’s email address can download the file.
+
+From 29 March 2023, we will turn this feature on by default for every file you send. Files sent before 29 March will not be affected.
+
+##### Turn on email address check
+
+To use this feature before 29 March 2023 you will need version 5.2.0 of the Node.js client library, or a more recent version.
+
+To make the recipient confirm their email address before downloading the file, set the `confirmEmailBeforeDownload` flag to `true`.
+
+You will not need to do this after 29 March.
+
+```javascript
+var fs = require('fs')
+
+fs.readFile('path/to/document.pdf', function (err, pdfFile) {
+  console.log(err)
+  notifyClient.sendEmail(templateId, emailAddress, {
+    personalisation: {
+      first_name: 'Amala',
+      application_date: '2018-01-01',
+      link_to_file: notifyClient.prepareUpload(pdfFile, false, true, undefined)
+    }
+  }).then(response => console.log(response)).catch(err => console.error(err))
+})
+```
+
+##### Turn off email address check (not recommended)
+
+If you do not want to use this feature after 29 March 2023, you can turn it off on a file-by-file basis.
+
+To do this you will need version 5.2.0 of the Node.js client library, or a more recent version.
+
+You should not turn this feature off if you send files that contain:
+
+* personally identifiable information
+* commercially sensitive information
+* information classified as ‘OFFICIAL’ or ‘OFFICIAL-SENSITIVE’ under the [Government Security Classifications](https://www.gov.uk/government/publications/government-security-classifications) policy
+
+To let the recipient download the file without confirming their email address, set the `confirmEmailBeforeDownload` flag to `false`.
+
+```javascript
+var fs = require('fs')
+
+fs.readFile('path/to/document.pdf', function (err, pdfFile) {
+  console.log(err)
+  notifyClient.sendEmail(templateId, emailAddress, {
+    personalisation: {
+      first_name: 'Amala',
+      application_date: '2018-01-01',
+      link_to_file: notifyClient.prepareUpload(pdfFile, false, false, undefined)
+    }
+  }).then(response => console.log(response)).catch(err => console.error(err))
+})
+```
+
+#### Choose the length of time that a file is available to download
+
+Set the number of weeks you want the file to be available using the `retentionPeriod` parameter.
+
+You can choose any value between 1 week and 78 weeks.
+
+To use this feature will need version 5.2.0 of the Node.js client library, or a more recent version.
+
+If you do not choose a value, the file will be available for the default period of 78 weeks (18 months).
+
+```javascript
+var fs = require('fs')
+
+fs.readFile('path/to/document.pdf', function (err, pdfFile) {
+  console.log(err)
+  notifyClient.sendEmail(templateId, emailAddress, {
+    personalisation: {
+      first_name: 'Amala',
+      application_date: '2018-01-01',
+      link_to_file: notifyClient.prepareUpload(pdfFile, false, undefined, '52 weeks')
+    }
+  }).then(response => console.log(response)).catch(err => console.error(err))
+})
+```
+
 #### Response
 
 If the request is successful, the promise resolves with a `response` `object`. For example, the `response.data` property will look like this:
@@ -385,6 +477,8 @@ If the request is not successful, the promise fails with an `err`.
 |`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 file type '(FILE TYPE)'. Supported types are: '(ALLOWED TYPES)'"`<br>`}]`|Wrong file type. You can only upload .pdf, .csv, .txt, .doc, .docx, .xlsx, .rtf or .odt files|
+|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Unsupported value for retention_period '(PERIOD)'. Supported periods are from 1 to 78 weeks."`<br>`}]`|Choose a period between 1 and 78 weeks|
+|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Unsupported value for confirm_email_before_download: '(VALUE)'. Use a boolean true or false value."`<br>`}]`|Use either true or false|
 |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "File did not pass the virus scan"`<br>`}]`|The file contains a virus|
 |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Send files by email has not been set up - add contact details for your service at https://www.notifications.service.gov.uk/services/(SERVICE ID)/service-settings/send-files-by-email"`<br>`}]`|See how to [add contact details to the file download page](#add-contact-details-to-the-file-download-page)|
 |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can only send a file by email"`<br>`}]`|Make sure you are using an email template|

package/client/notification.js

@@ -115,6 +115,9 @@ function _check_and_encode_file(file, size_limit) {
   if (file.length > size_limit * 1024 * 1024) {
     throw "File is larger than " + String(size_limit) + "MB.";
   }
+  if (typeof(file) === 'string') {
+    file = Buffer.from(file);
+  }
   return file.toString('base64')
 }
 
@@ -344,15 +347,33 @@ Object.assign(NotifyClient.prototype, {
   /**
   *
   * @param {Buffer} fileData
-  * @param {Boolean} isCsv
+  * @param {object} options
   *
   * @returns {Dictionary}
   */
-  prepareUpload: function(fileData, isCsv = false) {
-    return {
-      'file': _check_and_encode_file(fileData, 2),
-      'is_csv': isCsv
+  prepareUpload: function(fileData, options) {
+    let data = {
+      file: _check_and_encode_file(fileData, 2),
+      is_csv: false,
+      confirm_email_before_download: null,
+      retention_period: null,
+    }
+
+    if (options !== undefined) {
+      if (typeof(options) === 'boolean') {
+        data.is_csv = options
+      }
+      else {
+        if (options.isCsv !== undefined) {
+          data.is_csv = options.isCsv;
+        }
+
+        data.confirm_email_before_download = options.confirmEmailBeforeDownload || null;
+        data.retention_period = options.retentionPeriod || null
+      }
     }
+
+    return data
   },
 
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notifications-node-client",
-  "version": "5.1.2",
+  "version": "5.2.1",
   "homepage": "https://docs.notifications.service.gov.uk/node.html",
   "repository": {
     "type": "git",

package/spec/notification.js

@@ -188,6 +188,59 @@ describe('notification api', () => {
         notifyClient.prepareUpload(file);
       }).to.throw("File is larger than 2MB.")
     });
+    it('should accept files as buffers (from fs.readFile with no encoding)', () => {
+      let fs = require('fs');
+      let file = fs.readFileSync('./spec/test_files/simple.csv');
+      expect(typeof(file)).to.equal('object')
+      expect(Buffer.isBuffer(file)).to.equal(true);
+      expect(
+        notifyClient.prepareUpload(file, true)
+      ).contains({file: 'MSwyLDMKYSxiLGMK', is_csv: true})
+    });
+    it('should accept files as strings (from fs.readFile with an encoding)', () => {
+      let fs = require('fs');
+      let file = fs.readFileSync('./spec/test_files/simple.csv', 'binary');
+      expect(typeof(file)).to.equal('string')
+      expect(Buffer.isBuffer(file)).to.equal(false);
+      expect(
+        notifyClient.prepareUpload(file, true)
+      ).contains({file: 'MSwyLDMKYSxiLGMK', is_csv: true})
+    });
+
+    it('should allow isCsv to be set with the old method (directly into options)', () => {
+      let file = Buffer.alloc(2*1024*1024)
+      expect(
+        notifyClient.prepareUpload(file, true)
+      ).contains({is_csv: true, confirm_email_before_download: null, retention_period: null})
+    });
+
+    it('should allow isCsv to be set as part of the options object', () => {
+      let file = Buffer.alloc(2*1024*1024)
+      expect(
+        notifyClient.prepareUpload(file, {isCsv: true})
+      ).contains({is_csv: true, confirm_email_before_download: null, retention_period: null})
+    });
+
+    it('should imply isCsv=false from empty options', () => {
+      let file = Buffer.alloc(2*1024*1024)
+      expect(
+        notifyClient.prepareUpload(file, {})
+      ).contains({is_csv: false, confirm_email_before_download: null, retention_period: null})
+    });
+
+    it('should allow send a file email confirmation to be set', () => {
+      let file = Buffer.alloc(2*1024*1024)
+      expect(
+        notifyClient.prepareUpload(file, {confirmEmailBeforeDownload: true})
+      ).contains({is_csv: false, confirm_email_before_download: true, retention_period: null})
+    });
+
+    it('should allow custom retention periods to be set', () => {
+      let file = Buffer.alloc(2*1024*1024)
+      expect(
+        notifyClient.prepareUpload(file, {retentionPeriod: "52 weeks"})
+      ).contains({is_csv: false, confirm_email_before_download: null, retention_period: '52 weeks'})
+    });
   });
 
   describe('sendSms', () => {

package/spec/test_files/simple.csv

@@ -0,0 +1,2 @@
+1,2,3
+a,b,c