Merge pull request #140 from alphagov/SW-custom-filename

Allow setting custom filenames for documents

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:

DOCUMENTATION.md

@@ -272,17 +272,30 @@ File.open("file.pdf", "rb") do |f|
 end
 ```
 
-##### CSV Files
+#### Set the filename
 
-Uploads for CSV files should use the `is_csv` parameter on the `prepare_upload()` helper method.  For example:
+To do this you will need version 6.0.0 of the Ruby client library, or a more recent version.
+
+You should provide a filename when you upload your file.
+
+The filename should tell the recipient what the file contains. A memorable filename can help the recipient to find the file again later.
+
+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.
+
+If you do not provide a filename for your file, Notify will:
+
+* generate a random filename
+* try to add the correct file extension
+
+If Notify cannot add the correct file extension, recipients may not be able to open your file.
 
 ```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),
+      link_to_file: Notifications.prepare_upload(f, filename="2023-12-25-daily-report.csv"),
     }
 end
 ```

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
 

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

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

spec/notifications/client/helper_methods_spec.rb

@@ -10,29 +10,29 @@
         result = Notifications.prepare_upload(f)
         f.rewind
 
-        expect(result).to eq(file: encoded_content, is_csv: false, confirm_email_before_download: nil, retention_period: nil)
+        expect(result).to eq(file: encoded_content, filename: nil, confirm_email_before_download: nil, retention_period: nil)
         expect(Base64.strict_decode64(encoded_content)).to eq(f.read)
       end
     end
 
     it "encodes a StringIO object" do
       input_string = StringIO.new("My document to send")
-      expect(Notifications.prepare_upload(input_string)).to eq(file: "TXkgZG9jdW1lbnQgdG8gc2VuZA==", is_csv: false, confirm_email_before_download: nil, retention_period: nil)
+      expect(Notifications.prepare_upload(input_string)).to eq(file: "TXkgZG9jdW1lbnQgdG8gc2VuZA==", filename: nil, confirm_email_before_download: nil, retention_period: nil)
     end
 
-    it "allows is_csv to be set to true" do
+    it "allows filename to be set" do
       input_string = StringIO.new("My document to send")
-      expect(Notifications.prepare_upload(input_string, true)).to eq(file: "TXkgZG9jdW1lbnQgdG8gc2VuZA==", is_csv: true, confirm_email_before_download: nil, retention_period: nil)
+      expect(Notifications.prepare_upload(input_string, filename: "report.csv")).to eq(file: "TXkgZG9jdW1lbnQgdG8gc2VuZA==", filename: "report.csv", confirm_email_before_download: nil, retention_period: nil)
     end
 
     it "allows confirm_email_before_download to be set to true" do
       input_string = StringIO.new("My document to send")
-      expect(Notifications.prepare_upload(input_string, confirm_email_before_download: true)).to eq(file: "TXkgZG9jdW1lbnQgdG8gc2VuZA==", is_csv: false, confirm_email_before_download: true, retention_period: nil)
+      expect(Notifications.prepare_upload(input_string, confirm_email_before_download: true)).to eq(file: "TXkgZG9jdW1lbnQgdG8gc2VuZA==", filename: nil, confirm_email_before_download: true, retention_period: nil)
     end
 
     it "allows retention_period to be set" do
       input_string = StringIO.new("My document to send")
-      expect(Notifications.prepare_upload(input_string, retention_period: '1 weeks')).to eq(file: "TXkgZG9jdW1lbnQgdG8gc2VuZA==", is_csv: false, confirm_email_before_download: nil, retention_period: '1 weeks')
+      expect(Notifications.prepare_upload(input_string, retention_period: '1 weeks')).to eq(file: "TXkgZG9jdW1lbnQgdG8gc2VuZA==", filename: nil, confirm_email_before_download: nil, retention_period: '1 weeks')
     end
 
     it "raises an error when the file size is too large" do