notifications-ruby-client 2.8.0 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7ebfa7945a861630914de5251f291bb5fac91f6d594b819364ca745072e6129
-  data.tar.gz: 8374e982bd9a519d85446dae5a4cb4808308ba80443f431ec1841f7ddbea54cb
+  metadata.gz: 0ee6c91540f71825cf6b96f6eb7e170383c2841bdc499bf45b625c2b0d48525c
+  data.tar.gz: eec0b7042a42330d7ab776eb39815928359a07ac732504738a64db5f2f06bf54
 SHA512:
-  metadata.gz: eb25a50ca0b7b0571f6908711ede2a3212fad478f7243538a88acc8c6bd7254eec1d670ba54dd6953281bf353d85b94ca05ecd99aa9de89bb4386306c74bdb18
-  data.tar.gz: 1e94b34627e331bb61e4e549efec4b8a6a50318665d3639b75b021f0d5b080f40ec7d73507d21b73c87db686d4f934016287ab65fd1ed0c0a92280eca91571d8
+  metadata.gz: e310f4d25c85ac58d741076fd586b0b6720e49f916ad500d47dbc781dc0e5023375231f1b8ff121523b0a154b34bf00ef1f8a27b3e62347c8b0fb6402889f04e
+  data.tar.gz: 97c23e6f67ccee843ae3534bd209e7a295322c87c43381109291bd8b78dc1b7dbe4f9b86d465ecfd1b51fc05be49c3af93c64acca9b786b6a2f6d80c4088df2d

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2.9.0
+
+* Added the `send_precompiled_letter` method which allows the client to send letters as PDF files.
+  * This requires two arguments - a reference for the letter and the PDF letter file. The file must conform to the Notify printing template.
+* Added support for document uploads using the `send_email` method.
+
 ## 2.8.0
 
 * Updated the Template class to have a `name` property, which is the name of the template as set in Notify.

data/DOCUMENTATION.md

@@ -207,6 +207,36 @@ email_reply_to_id: '8e222534-7f05-4972-86e3-17c5d9f894e2'
 
 You can leave out this argument if your service only has one email reply-to address, or you want to use the default email address.
 
+### 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 an argument to the `Notifications.prepare_upload` helper method. Then pass the result into the personalisation argument. For example:
+
+```ruby
+File.open("file.pdf", "rb") do |f|
+    ...
+    personalisation: {
+      first_name: "Amala",
+      application_date: "2018-01-01",
+      link_to_document: Notifications.prepare_upload(f),
+    }
+end
+```
+
 ### Response
 
 If the request to the client is successful, the client returns a `Notifications::Client:ResponseNotification` object. In the example shown in the [Method section](/ruby.html#send-an-email-method), the object is named `emailresponse`.
@@ -229,11 +259,14 @@ If the request is not successful, the client returns a `Notifications::Client::R
 |:--- |:---|:---|
 |`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](/ruby.html#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 API key. Refer to [API keys](/ruby.html#api-keys) for more information|
 |`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](/ruby.html#api-rate-limits) for more information|
 |`429`|`[{`<br>`"error": "TooManyRequestsError",`<br>`"message": "Exceeded send limits (LIMIT NUMBER) for today"`<br>`}]`|Refer to [service limits](/ruby.html#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|
+|-|`[{`<br>`"error": "ArgumentError",`<br>`"message": "Document is larger than 2MB")`<br>`}]`|Document size was too large, upload a smaller document|
 
 ## Send a letter
 
@@ -338,6 +371,56 @@ If the request is not successful, the client returns a `Notifications::Client::R
 |`429`|`[{`<br>`"error": "TooManyRequestsError",`<br>`"message": "Exceeded send limits (LIMIT NUMBER) for today"`<br>`}]`|Refer to [service limits](/ruby.html#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|
 
+## Send a pre-compiled letter
+This is an invitation-only feature. Contact the GOV.UK Notify team on the [support page](https://www.notifications.service.gov.uk/support) or through the [Slack channel](https://ukgovernmentdigital.slack.com/messages/govuk-notify) for more information.
+
+### Method
+```ruby
+precompiled_letter = client.send_precompiled_letter(reference, pdf_file)
+```
+
+### Arguments
+
+#### reference (required)
+A unique identifier you create. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address.
+
+#### pdf_file (required)
+The pre-compiled letter must be a PDF file.
+
+```ruby
+File.open("path/to/pdf_file", "rb") do |pdf_file|
+    client.send_precompiled_letter("your reference", pdf_file)
+end
+```
+
+### Response
+
+If the request to the client is successful, the client returns a `Notifications::Client:ResponseNotification` object. In the example shown in the [Method section](/ruby.html#send-a-pre-compiled-letter-method), the object is named `precompiled_letter`.
+
+You can then call different methods on this object to return the requested information.
+
+|Method|Information|Type|
+|:---|:---|:---|
+|`precompiled_letter.id`|Notification UUID|String|
+|`precompiled_letter.reference`|`reference` argument|String|
+|`precompiled_letter.content`|Always `nil`|nil|
+|`precompiled_letter.template`|Always `nil`|nil|
+|`precompiled_letter.uri`|Always `nil`|nil|
+
+### Error codes
+
+If the request is not successful, the client returns a `Notifications::Client::RequestError` and an error code.
+
+|error.status_code|error.message|How to fix|
+|:---|:---|:---|
+|`429`|`[{`<br>`"error": "RateLimitError",`<br>`"message": "Exceeded rate limit for key type live of 10 requests per 20 seconds"`<br>`}]`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
+|`429`|`[{`<br>`"error": "TooManyRequestsError",`<br>`"message": "Exceeded send limits (50) for today"`<br>`}]`|Refer to [service limits](#service-limits) for the limit number|
+|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Cannot send letters with a team api key"`<br>`]}`|Use the correct type of [API key](#api-keys)|
+|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Cannot send precompiled letters"`<br>`]}`|This is an invitation-only feature. Contact the GOV.UK Notify team on the [support page](https://www.notifications.service.gov.uk/support) or through the [Slack channel](https://ukgovernmentdigital.slack.com/messages/govuk-notify) for more information|
+|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Letter content is not a valid PDF"`<br>`]}`|PDF file format is required|
+|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Cannot send letters 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": "ValidationError",`<br>`"message": "reference is a required property"`<br>`}]`|Add a `reference` argument to the method call|
+
 # Get message status
 
 Message status depends on the type of message that you have sent.

data/bin/test_client.rb

@@ -9,11 +9,15 @@ def main
   test_get_all_templates_filter_by_type(client)
   test_generate_template_preview(client, ENV['EMAIL_TEMPLATE_ID'])
   email_notification = test_send_email_endpoint(client)
+  email_notification_with_document = test_send_email_endpoint_with_document(client)
   sms_notification = test_send_sms_endpoint(client)
   letter_notification = test_send_letter_endpoint(client)
+  precompiled_letter_notification = test_send_precompiled_letter_endpoint(client)
   test_get_notification_by_id_endpoint(client, email_notification.id, 'email')
+  test_get_notification_by_id_endpoint(client, email_notification_with_document.id, 'email')
   test_get_notification_by_id_endpoint(client, sms_notification.id, 'sms')
   test_get_notification_by_id_endpoint(client, letter_notification.id, 'letter')
+  test_get_notification_by_id_endpoint(client, precompiled_letter_notification.id, 'precompiled_letter')
   test_get_all_notifications(client)
   test_get_received_texts
   p 'ruby client integration tests pass'
@@ -97,6 +101,19 @@ def test_send_email_endpoint(client)
   email_resp
 end
 
+def test_send_email_endpoint_with_document(client)
+  email_resp = File.open('spec/test_files/test_pdf.pdf', 'rb') do |f|
+    client.send_email(email_address: ENV['FUNCTIONAL_TEST_EMAIL'],
+      template_id: ENV['EMAIL_TEMPLATE_ID'],
+      personalisation: { name: Notifications.prepare_upload(f) },
+      reference: "some reference",
+      email_reply_to_id: ENV['EMAIL_REPLY_TO_ID'])
+  end
+
+  test_notification_response_data_type(email_resp, 'email')
+  email_resp
+end
+
 def test_send_sms_endpoint(client)
   sms_resp = client.send_sms(phone_number: ENV['FUNCTIONAL_TEST_NUMBER'], template_id: ENV['SMS_TEMPLATE_ID'],
                              personalisation: { "name" => "some name" },
@@ -120,6 +137,16 @@ def test_send_letter_endpoint(client)
   letter_resp
 end
 
+def test_send_precompiled_letter_endpoint(client)
+  precompiled_letter_resp = File.open('spec/test_files/test_pdf.pdf', 'rb') do |file|
+    client.send_precompiled_letter("some reference", file)
+  end
+
+  test_notification_response_data_type(precompiled_letter_resp, 'precompiled_letter')
+
+  precompiled_letter_resp
+end
+
 def test_notification_response_data_type(notification, message_type)
   unless notification.is_a?(Notifications::Client::ResponseNotification)
     p 'failed ' + message_type + ' response is not a Notifications::Client::ResponseNotification'
@@ -129,6 +156,12 @@ def test_notification_response_data_type(notification, message_type)
     p 'failed ' + message_type + 'id is not a String'
     exit 1
   end
+
+  if message_type == 'precompiled_letter'
+    field_should_not_be_nil(expected_fields_in_precompiled_letter_response, notification, 'send_precompiled_letter')
+    return
+  end
+
   field_should_not_be_nil(expected_fields_in_notification_response, notification, 'send_' + message_type)
   hash_key_should_not_be_nil(expected_fields_in_template, notification.send('template'), 'send_' + message_type + '.template')
 
@@ -161,6 +194,10 @@ def test_get_notification_by_id_endpoint(client, id, message_type)
     field_should_not_be_nil(expected_fields_in_letter_notification, get_notification_response, 'Notifications::Client::Notification for type letter')
     field_should_be_nil(expected_fields_in_letter_notification_that_are_nil, get_notification_response, 'Notifications::Client::Notification for type letter')
     hash_key_should_not_be_nil(expected_fields_in_template, get_notification_response.send('template'), 'Notifications::Client::Notification.template for type letter')
+  elsif message_type == 'precompiled_letter'
+    field_should_not_be_nil(expected_fields_in_precompiled_letter_notification, get_notification_response, 'Notifications::Client::Notification for type precompiled letter')
+    field_should_be_nil(expected_fields_in_precompiled_letter_notification_that_are_nil, get_notification_response, 'Notifications::Client::Notification for type precompiled letter')
+    hash_key_should_not_be_nil(expected_fields_in_template, get_notification_response.send('template'), 'Notifications::Client::Notification.template for type precompiled letter')
   end
 end
 
@@ -216,6 +253,11 @@ def expected_fields_in_notification_response
      uri)
 end
 
+def expected_fields_in_precompiled_letter_response
+  %w(id
+     reference)
+end
+
 def expected_fields_in_email_content
   %w(from_email
      body
@@ -223,7 +265,8 @@ def expected_fields_in_email_content
 end
 
 def expected_fields_in_sms_content
-  %w(body)
+  %w(body
+    from_number)
 end
 
 def expected_fields_in_letter_content
@@ -309,6 +352,36 @@ def expected_fields_in_letter_notification_that_are_nil
   )
 end
 
+def expected_fields_in_precompiled_letter_notification
+  %w(
+    body
+    created_at
+    id
+    line_1
+    reference
+    status
+    subject
+    template
+    type
+  )
+end
+
+def expected_fields_in_precompiled_letter_notification_that_are_nil
+  %w(
+    completed_at
+    created_by_name
+    email_address
+    line_2
+    line_3
+    line_4
+    line_5
+    line_6
+    phone_number
+    postcode
+    sent_at
+  )
+end
+
 def expected_fields_in_template
   %w(id
      version

data/lib/notifications/client.rb

@@ -9,6 +9,7 @@ require_relative "client/response_template"
 require_relative "client/template_collection"
 require_relative "client/template_preview"
 require_relative "client/uuid_validator"
+require_relative "client/helper_methods"
 require "forwardable"
 
 module Notifications
@@ -16,6 +17,7 @@ module Notifications
     attr_reader :speaker
 
     PRODUCTION_BASE_URL = "https://api.notifications.service.gov.uk".freeze
+    MAX_FILE_UPLOAD_SIZE = 2 * 1024 * 1024 # 2MB limit on uploaded documents
 
     extend Forwardable
     def_delegators :speaker, :service_id, :secret_token, :base_url, :base_url=
@@ -53,6 +55,17 @@ module Notifications
       )
     end
 
+    ##
+    # @param reference [String]
+    # @param pdf_file [File]
+    # @see Notifications::Client::Speaker#post_precompiled_letter
+    # @return [ResponseNotification]
+    def send_precompiled_letter(reference, pdf_file)
+      ResponseNotification.new(
+        speaker.post_precompiled_letter(reference, pdf_file)
+      )
+    end
+
     ##
     # @param id [String]
     # @see Notifications::Client::Speaker#get

data/lib/notifications/client/helper_methods.rb

@@ -0,0 +1,9 @@
+require "base64"
+
+module Notifications
+  def self.prepare_upload(file)
+    raise ArgumentError.new("Document is larger than 2MB") if file.size > Client::MAX_FILE_UPLOAD_SIZE
+
+    { file: Base64.strict_encode64(file.read) }
+  end
+end

data/lib/notifications/client/speaker.rb

@@ -1,3 +1,4 @@
+require "base64"
 require "net/https"
 require "uri"
 require "jwt"
@@ -95,6 +96,22 @@ module Notifications
         perform_request!(request)
       end
 
+      ##
+      # @param reference [String] reference of the notification
+      # @param pdf_file [File] PDF file opened for reading
+      # @see #perform_request!
+      def post_precompiled_letter(reference, pdf_file)
+        content = Base64.strict_encode64(pdf_file.read)
+        form_data = { reference: reference, content: content }
+
+        request = Net::HTTP::Post.new(
+          "#{BASE_PATH}/letter",
+          headers
+        )
+        request.body = form_data.to_json
+        perform_request!(request)
+      end
+
     private
 
       ##
@@ -103,7 +120,7 @@ module Notifications
       #   not successful
       def perform_request!(request)
         response = open(request)
-        if response.is_a?(Net::HTTPClientError)
+        if response.is_a?(Net::HTTPClientError) || response.is_a?(Net::HTTPServerError)
           raise RequestError.new(response)
         else
           JSON.parse(response.body)

data/lib/notifications/client/uuid_validator.rb

@@ -23,4 +23,3 @@ module Notifications
     end
   end
 end
-

data/lib/notifications/client/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: notifications-ruby-client
 version: !ruby/object:Gem::Version
-  version: 2.8.0
+  version: 2.9.0
 platform: ruby
 authors:
 - Government Digital Service
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-09-05 00:00:00.000000000 Z
+date: 2018-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jwt
@@ -140,6 +140,7 @@ files:
 - docker/Dockerfile
 - docker/Makefile
 - lib/notifications/client.rb
+- lib/notifications/client/helper_methods.rb
 - lib/notifications/client/notification.rb
 - lib/notifications/client/notifications_collection.rb
 - lib/notifications/client/received_text.rb