notifications-ruby-client 5.4.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6827c0db7ff51cabb102005e382e49fb225344a2856b11f85dc4edc799b9d9a9
-  data.tar.gz: 222318524a806a4ce707cdc3fff989b6d91f28fffa106fe9235584d14b1cd2f1
+  metadata.gz: 0b04d33af2550021b9eecec2c063c360f349715c33353be054d9e2f7e4463896
+  data.tar.gz: e4d0f5ece925c71a0ecfbc779bf27a94d29c8d7019b75b4b42955498ba58b2fe
 SHA512:
-  metadata.gz: ef8a9234c0e8a4730d9ce2561d35261882903090bbaeaaad29540b36a1622c77ff0953d395ed0976093e962cae92cd304f2ace1579ce41d5b3e70553528ee1d5
-  data.tar.gz: 44f09776241452471cacea7cec73bfa4ab158ed24f5a4a631bcdf747923cd18f66f34b0e8742dcc036dd2f4dd646dbc3a095e24736cac10452d4dc555105b4f9
+  metadata.gz: 9158493f4a551508d9b4267fde147f345e0c0c47e5f46319bd92394b7a072d3b2c2543c9df841c0433685a86dd04eb1fb17fb5d6d18eede029ce11e6c798a65e
+  data.tar.gz: be9ea47296e25def1236762ab0d3e00d6e72a2e0548b94aaa81cf2770e8d2ac976cfb5b6df8223a7f5db56e57de7f9375c84561b31e9b9af928f5554a97e5720

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 6.0.0
+
+* Removes the `is_csv` parameter from `prepare_upload`
+* Adds a `filename` parameter to `prepare_upload` to set the filename of the document upon download. See the documentation for more information.
+
 ## 5.4.0
 
 * Add support for new security features when sending a file by email:

data/DOCUMENTATION.md

@@ -12,7 +12,7 @@ Run the following in the command line:
 gem install 'notifications-ruby-client'
 ```
 
-Refer to the [client changelog](https://github.com/alphagov/notifications-ruby-client/blob/master/CHANGELOG.md) for the version number and the latest updates.
+Refer to the [client changelog](https://github.com/alphagov/notifications-ruby-client/blob/main/CHANGELOG.md) for the version number and the latest updates.
 
 ### Create a new instance of the client
 
@@ -185,7 +185,9 @@ If a template has placeholder fields for personalised information such as name o
 ```ruby
 personalisation: {
   name: "John Smith",
-  year: "2016"
+  year: "2016",
+  # pass in an array and it will appear as bullet points in the message:
+  required_documents: ["passport", "utility bill", "other id"],
 }
 ```
 
@@ -227,15 +229,13 @@ To send a file by email, add a placeholder to the template then upload a file. T
 
 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.
+Your file will be available to download for a default period of 26 weeks (6 months).
 
 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.4.0 of the Ruby 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).
@@ -254,7 +254,7 @@ Your email should also tell recipients how long the file will be available to do
 
 #### Upload your file
 
-You can upload PDF, CSV, .odt, .txt, .rtf, .xlsx and MS Word Document files. Your file must be smaller than 2MB. [Contact the GOV.UK Notify team](https://www.notifications.service.gov.uk/support/ask-question-give-feedback) if you need to send other file types.
+You can upload PDF, CSV, JSON, .odt, .txt, .rtf, .xlsx and MS Word Document files. Your file must be smaller than 2MB. [Contact the GOV.UK Notify team](https://www.notifications.service.gov.uk/support/ask-question-give-feedback) if you need to send other file types.
 
 1. Pass the file object as an argument to the `Notifications.prepare_upload` helper method.
 1. Pass the result into the personalisation argument.
@@ -272,51 +272,43 @@ File.open("file.pdf", "rb") do |f|
 end
 ```
 
-##### CSV Files
-
-Uploads for CSV files should use the `is_csv` parameter on the `prepare_upload()` helper method.  For example:
-
-```ruby
-File.open("file.csv", "rb") do |f|
-    ...
-    personalisation: {
-      first_name: "Amala",
-      application_date: "2018-01-01",
-      link_to_file: Notifications.prepare_upload(f, is_csv=true),
-    }
-end
-```
-
-#### Ask recipients to confirm their email address before they can download the file
+#### Set the filename
 
-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.
+To do this you will need version 6.0.0 of the Ruby client library, or a more recent version.
 
-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.
+You should provide a filename when you upload your 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.
+The filename should tell the recipient what the file contains. A memorable filename can help the recipient to find the file again later.
 
-##### Turn on email address check
+The filename must end with a file extension. For example, `.csv` for a CSV file. If you include the wrong file extension, recipients may not be able to open your file.
 
-To use this feature before 29 March 2023 you will need version 5.4.0 of the Ruby client library, or a more recent version.
+If you do not provide a filename for your file, Notify will:
 
-To make the recipient confirm their email address before downloading the file, set the `confirm_email_before_download` flag to `true`.
+* generate a random filename
+* try to add the correct file extension
 
-You will not need to do this after 29 March.
+If Notify cannot add the correct file extension, recipients may not be able to open your file.
 
 ```ruby
-File.open("file.pdf", "rb") do |f|
+File.open("file.csv", "rb") do |f|
     ...
     personalisation: {
       first_name: "Amala",
       application_date: "2018-01-01",
-      link_to_file: Notifications.prepare_upload(f, confirm_email_before_download: true),
+      link_to_file: Notifications.prepare_upload(f, filename="2023-12-25-daily-report.csv"),
     }
 end
 ```
 
+#### Ask recipients to confirm their email address before they can download the file
+
+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.
+
+This security feature is turned on by default.
+
 ##### 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.
+If you do not want to use this feature, you can turn it off on a file-by-file basis.
 
 To do this you will need version 5.4.0 of the Ruby client library, or a more recent version.
 
@@ -345,11 +337,16 @@ end
 
 Set the number of weeks you want the file to be available using the `retention_period` key.
 
-You can choose any value between 1 week and 78 weeks.
-
 To use this feature will need version 5.4.0 of the Ruby 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).
+You can choose any value between 1 week and 78 weeks. When deciding this, you should consider:
+
+* the need to protect the recipient’s personal information
+* whether the recipient will need to download the file again later
+
+If you do not choose a value, the file will be available for the default period of 26 weeks (6 months).
+
+Files sent before 12 April 2023 had a longer default period of 78 weeks (18 months).
 
 ```ruby
 File.open("file.pdf", "rb") do |f|
@@ -385,8 +382,8 @@ If the request is not successful, the client raises a `Notifications::Client::Re
 |`400`|`BadRequestError: Can't send to this recipient using a team-only API key`|`BadRequestError`|Use the correct type of [API key](#api-keys)|
 |`400`|`BadRequestError: Can't send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode`|`BadRequestError`|Your service cannot send this notification in [trial mode](https://www.notifications.service.gov.uk/features/using-notify#trial-mode)|
 |`400`|`BadRequestError: Unsupported file type '(FILE TYPE)'. Supported types are: '(ALLOWED TYPES)'`|`BadRequestError`|Wrong file type. You can only upload .pdf, .csv, .txt, .doc, .docx, .xlsx, .rtf or .odt files|
-|`400`|`BadRequestError: Unsupported value for retention_period '(PERIOD)'. Supported periods are from 1 to 78 weeks.`|Choose a period between 1 and 78 weeks|
-|`400`|`BadRequestError: Unsupported value for confirm_email_before_download: '(VALUE)'. Use a boolean true or false value.`|Use either true or false|
+|`400`|`BadRequestError: Unsupported value for retention_period '(PERIOD)'. Supported periods are from 1 to 78 weeks.`|`BadRequestError`|Choose a period between 1 and 78 weeks|
+|`400`|`BadRequestError: Unsupported value for confirm_email_before_download: '(VALUE)'. Use a boolean true or false value.`|`BadRequestError`|Use either true or false|
 |`400`|`BadRequestError: File did not pass the virus scan`|`BadRequestError`|The file contains a virus|
 |`400`|`BadRequestError: 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`|`BadRequestError`|See how to [add contact details to the file download page](#add-contact-details-to-the-file-download-page)|
 |`400`|`BadRequestError: Can only send a file by email` | `BadRequestError`|Make sure you are using an email template|
@@ -465,7 +462,9 @@ personalisation: {
   address_line_2: '123 High Street', # mandatory address field
   address_line_3: 'SW14 6BH',  # mandatory address field
   name: 'John Smith', # field from template
-  application_date: '2018-01-01' # field from template
+  application_date: '2018-01-01' # field from template,
+  # pass in an array and it will appear as bullet points in the letter:
+  required_documents: ["passport", "utility bill", "other id"],
 },
 ```
 
@@ -760,7 +759,7 @@ If the request is not successful, the client raises a `Notifications::Client::Re
 |#`sending`|GOV.UK Notify has sent the message to the provider. The provider will try to deliver the message to the recipient for up to 72 hours. GOV.UK Notify is waiting for delivery information.|
 |#`pending`|GOV.UK Notify is waiting for more delivery information.<br>GOV.UK Notify received a callback from the provider but the recipient’s device has not yet responded. Another callback from the provider determines the final status of the text message.|
 |#`sent`|The message was sent to an international number. The mobile networks in some countries do not provide any more delivery information. The GOV.UK Notify website displays this status as 'Sent to an international number'.|
-|#`delivered`|The message was successfully delivered.|
+|#`delivered`|The message was successfully delivered. If a recipient blocks your sender name or mobile number, your message will still show as delivered.|
 |#`permanent-failure`|The provider could not deliver the message. This can happen if the phone number was wrong or if the network operator rejects the message. If you’re sure that these phone numbers are correct, you should [contact GOV.UK Notify support](https://www.notifications.service.gov.uk/support). If not, you should remove them from your database. You’ll still be charged for text messages that cannot be delivered.
 |#`temporary-failure`|The provider could not deliver the message. This can happen when the recipient’s phone is off, has no signal, or their text message inbox is full. You can try to send the message again. You’ll still be charged for text messages to phones that are not accepting messages.|
 |#`technical-failure`|Your message was not sent because there was a problem between Notify and the provider.<br>You’ll have to try sending your messages again. You will not be charged for text messages that are affected by a technical failure.|
@@ -1059,7 +1058,10 @@ You can also set up [callbacks](#callbacks) for received text messages.
 
 ### Enable received text messages
 
-Contact the GOV.UK Notify team using the [support page](https://www.notifications.service.gov.uk/support) or [chat to us on Slack](https://ukgovernmentdigital.slack.com/messages/C0E1ADVPC) to request a unique number for text message replies.
+To receive text messages:
+
+1. Go to the **Text message settings** section of the **Settings** page.
+1. Select **Change** on the **Receive text messages** row.
 
 ### Get a page of received text messages
 

data/README.md

@@ -6,5 +6,5 @@ Useful links:
 
 - [Documentation](https://docs.notifications.service.gov.uk/ruby.html)
 - [Ruby gem](https://rubygems.org/gems/notifications-ruby-client)
-- [Changelog](https://github.com/alphagov/notifications-ruby-client/blob/master/CHANGELOG.md)
-- [Contributing to this client](https://github.com/alphagov/notifications-ruby-client/blob/master/CONTRIBUTING.md)
+- [Changelog](https://github.com/alphagov/notifications-ruby-client/blob/main/CHANGELOG.md)
+- [Contributing to this client](https://github.com/alphagov/notifications-ruby-client/blob/main/CONTRIBUTING.md)

data/lib/notifications/client/helper_methods.rb

@@ -1,11 +1,12 @@
 require "base64"
 
 module Notifications
-  def self.prepare_upload(file, is_csv=false, confirm_email_before_download: nil, retention_period: nil)
+  def self.prepare_upload(file, filename: nil, confirm_email_before_download: nil, retention_period: nil)
     raise ArgumentError.new("File is larger than 2MB") if file.size > Client::MAX_FILE_UPLOAD_SIZE
 
-    data = { file: Base64.strict_encode64(file.read), is_csv: is_csv }
+    data = { file: Base64.strict_encode64(file.read) }
 
+    data[:filename] = filename
     data[:confirm_email_before_download] = confirm_email_before_download
     data[:retention_period] = retention_period
 

data/lib/notifications/client/version.rb

@@ -9,6 +9,6 @@
 
 module Notifications
   class Client
-    VERSION = "5.4.0".freeze
+    VERSION = "6.0.0".freeze
   end
 end

data/notifications-ruby-client.gemspec

@@ -26,5 +26,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.7"
   spec.add_development_dependency "webmock", "~> 3.4"
-  spec.add_development_dependency "factory_bot", "~> 6.1"
+  spec.add_development_dependency "factory_bot", "~> 6.1", "<6.4.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: notifications-ruby-client
 version: !ruby/object:Gem::Version
-  version: 5.4.0
+  version: 6.0.0
 platform: ruby
 authors:
 - Government Digital Service
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-10-06 00:00:00.000000000 Z
+date: 2024-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jwt
@@ -93,6 +93,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 6.4.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -100,6 +103,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 6.4.5
 description: 
 email:
 - notify@digital.cabinet-office.gov.uk