notifications-ruby-client 4.0.0 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bb224294830c1d0d4c4d776597d7ce144ca14fb993500f432275188914ab4cb
-  data.tar.gz: 94b010994127fbb3bcea06a408ec33587b3dbef34b8eaf404f6ece05d26eaf5b
+  metadata.gz: c8273dcafdfbd624d66c297df116923b57e7dbc336403f982c605a97842b4753
+  data.tar.gz: eedca7b3d118bea2476cedebb32c6c802ffb8322612ec1c97eb0bbb0bbe21408
 SHA512:
-  metadata.gz: 3c9f30f36f38523e8c36a784b9780f434f3cc798b9e6824dcbfa06dd2fcb96802dff67c9dd2affe7c294243929ab734da477aea8c89dc39aa9646aba8e815966
-  data.tar.gz: cd81acb5965952e29c3e5c26c6c5c6144b8a8eca2b60ee6e2a40e81789f839c2d7876dd7f2b492c157585e16f19f184b8bef0eb6aa23eb502bee89d53a2a6885
+  metadata.gz: 6cc4249443eb6e24751de8b9c7ac410afabd6b1235ae9cbde437984734602ba3b5466de56afa02143278d5fcef2425f5b7243792bf5bce9a5a0a917e7bd51fbf
+  data.tar.gz: 910a3f1e534c95a7d1fc547bcd4752eb439b73d54208819f735bdf540b48473e7455e20cbd3ee281429df063ddd049c99300f3ac800fa141010d7cf0830bf5ae

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 5.1.0
+
+* Added new `get_pdf_for_letter` method
+  * accepts a notification id argument
+  * returns a string containing the final printable PDF for a precompiled or templated letter
+
+## 5.0.0
+
+* Dropped support for Ruby 2.3. Official support for this version ended in March (https://www.ruby-lang.org/en/news/2019/03/31/support-of-ruby-2-3-has-ended/)
+
 ## 4.0.0
 
 * `RequestError.message` now returns a string, not an array of hashes – see https://github.com/alphagov/notifications-ruby-client/pull/72

data/DOCUMENTATION.md

@@ -2,8 +2,6 @@
 
 This documentation is for developers interested in using the GOV.UK Notify Ruby client to send emails, text messages or letters.
 
-We recommend that you use this client library rather than use the [GOV.UK Notify API](https://github.com/alphagov/notifications-api) directly, as there is no documentation for using the API in this way.
-
 # Set up the client
 
 ## Install the client
@@ -25,7 +23,7 @@ require 'notifications/client'
 client = Notifications::Client.new(api_key)
 ```
 
-To get an API key, [sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/) and go to the __API integration__ page. You can find more information in the [API keys](/ruby.html#api-keys) section of this documentation.
+To get an API key, [sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/) and go to the __API integration__ page. You can find more information in the [API keys](#api-keys) section of this documentation.
 
 # Send a message
 
@@ -67,7 +65,7 @@ If a template has placeholder fields for personalised information such as name o
 ```ruby
 personalisation: {
   name: "John Smith",
-  ID: "300241",                      
+  ID: "300241",
 }
 ```
 
@@ -108,7 +106,7 @@ You can leave out this argument if your service only has one text message sender
 
 ### 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#method), the object is named `smsresponse`.
+If the request to the client is successful, the client returns a `Notifications::Client:ResponseNotification` object. In the example shown in the [Method section](#method), the object is named `smsresponse`.
 
 You can then call different methods on this object:
 
@@ -120,7 +118,7 @@ You can then call different methods on this object:
 |`smsresponse.template`|Contains the `id`, `version` and `uri` of the template|Hash|
 |`smsresponse.uri`|Notification URL|String|
 
-If you are using the [test API key](/ruby.html#test), all your messages come back with a `delivered` status.
+If you are using the [test API key](#test), all your messages come back with a `delivered` status.
 
 All messages sent using the [team and whitelist](#team-and-whitelist) or [live](#live) keys appear on your GOV.UK Notify dashboard.
 
@@ -130,12 +128,12 @@ If the request is not successful, the client returns a `Notifications::Client::R
 
 |error.code|error.message|class|How to fix|
 |:---|:---|:---|:---|
-|`400`|`BadRequestError: Can't send to this recipient using a team-only API key`|`BadRequestError`|Use the correct type of [API key](/ruby.html#api-keys)|
+|`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)|
 |`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
-|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
-|`429`|`RateLimitError: Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds`|`RateLimitError`|Refer to [API rate limits](/ruby.html#api-rate-limits) for more information|
-|`429`|`TooManyRequestsError: Exceeded send limits (LIMIT NUMBER) for today`|`ClientError`|Refer to [service limits](/ruby.html#service-limits) for the limit number|
+|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
+|`429`|`RateLimitError: Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds`|`RateLimitError`|Refer to [API rate limits](#api-rate-limits) for more information|
+|`429`|`TooManyRequestsError: Exceeded send limits (LIMIT NUMBER) for today`|`ClientError`|Refer to [service limits](#service-limits) for the limit number|
 |`500`|`Exception: Internal server error`|`ServerError`|Notify was unable to process the request, resend your notification|
 
 ## Send an email
@@ -174,7 +172,7 @@ If a template has placeholder fields for personalised information such as name o
 ```ruby
 personalisation: {
   name: "John Smith",
-  year: "2016"                      
+  year: "2016"
 }
 ```
 
@@ -209,13 +207,15 @@ 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 a file by email
 
 Send files without the need for email attachments.
 
-This is an invitation-only feature. [Contact the GOV.UK Notify team](https://www.notifications.service.gov.uk/support) to enable this function for your service.
+This is an invitation-only feature. [Contact the GOV.UK Notify team](https://www.notifications.service.gov.uk/support/ask-question-give-feedback) to enable this function for your service.
+
+To send a file by email, add a placeholder field to the template then upload a file. The placeholder field will contain a secure link to download the file.
 
-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.
+The links are unique and unguessable. GOV.UK Notify cannot access or decrypt your file.
 
 ### Add a placeholder field to the template
 
@@ -223,11 +223,11 @@ To send a document by email, add a placeholder field to the template then upload
 1. Go to the __Templates__ page and select the relevant email template.
 1. Add a placeholder field to the email template using double brackets. For example:
 
-"Download your document at: ((link_to_document))"
+"Download your file at: ((link_to_document))"
 
-### Upload your document
+### Upload your file
 
-The document you upload must be a PDF file smaller than 2MB.
+The file you upload must be a PDF file smaller than 2MB.
 
 1. Pass the file object as an argument to the `Notifications.prepare_upload` helper method.
 1. Pass the result into the personalisation argument.
@@ -247,7 +247,7 @@ 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`.
+If the request to the client is successful, the client returns a `Notifications::Client:ResponseNotification` object. In the example shown in the [Method section](#send-an-email-method), the object is named `emailresponse`.
 
 You can then call different methods on this object to return the requested information.
 
@@ -265,15 +265,15 @@ If the request is not successful, the client returns a `Notifications::Client::R
 
 |error.code|error.message|class|How to fix|
 |:--- |:---|:---|:---|
-|`400`|`BadRequestError: Can't send to this recipient using a team-only API key`|`BadRequestError`|Use the correct type of [API key](/ruby.html#api-keys)|
+|`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 document type '{}'. Supported types are: {}`|`BadRequestError`|The document you upload must be a PDF file|
 |`400`|`BadRequestError: Document didn't pass the virus scan`|`BadRequestError`|The document you upload must be virus free|
 |`400`|`BadRequestError: Service is not allowed to send documents`|`BadRequestError`|Contact the GOV.UK Notify team|
 |`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
-|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
-|`429`|`RateLimitError: Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds`|`RateLimitError`|Refer to [API rate limits](/ruby.html#api-rate-limits) for more information|
-|`429`|`TooManyRequestsError: Exceeded send limits (LIMIT NUMBER) for today`|`RateLimitError`|Refer to [service limits](/ruby.html#service-limits) for the limit number|
+|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
+|`429`|`RateLimitError: Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds`|`RateLimitError`|Refer to [API rate limits](#api-rate-limits) for more information|
+|`429`|`TooManyRequestsError: Exceeded send limits (LIMIT NUMBER) for today`|`RateLimitError`|Refer to [service limits](#service-limits) for the limit number|
 |`500`|`Exception: Internal server error`|`ServerError`|Notify was unable to process the request, resend your notification|
 |-|`ArgumentError: Document is larger than 2MB")`|-|Document size was too large, upload a smaller document|
 
@@ -291,7 +291,7 @@ When your service first signs up to GOV.UK Notify, you’ll start in trial mode.
 letterresponse = client.send_letter(
   template_id: "f33517ff-2a88-4f6e-b855-c550268ce08a",
   personalisation: {
-    address_line_1: 'The Occupier',  
+    address_line_1: 'The Occupier',
     address_line_2: '123 High Street',
     postcode: 'SW14 6BH',
   },
@@ -352,7 +352,7 @@ reference: 'your_reference_string'
 
 ### 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-letter-method), the object is named `letterresponse`.
+If the request to the client is successful, the client returns a `Notifications::Client:ResponseNotification` object. In the example shown in the [Method section](#send-a-letter-method), the object is named `letterresponse`.
 
 You can then call different methods on this object to return the requested information.
 
@@ -371,13 +371,13 @@ If the request is not successful, the client returns a `Notifications::Client::R
 
 |error.code|error.message|class|How to fix|
 |:--- |:---|:---|:---|
-|`400`|`BadRequestError: Cannot send letters with a team api key`|`BadRequestError`|Use the correct type of [API key](/ruby.html#api-keys)|
+|`400`|`BadRequestError: Cannot send letters with a team api key`|`BadRequestError`|Use the correct type of [API key](#api-keys)|
 |`400`|`BadRequestError: Cannot send letters 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`|`ValidationError: personalisation address_line_1 is a required property`|`BadRequestError`|Ensure that your template has a field for the first line of the address, refer to [personalisation](/ruby.html#personalisation-required) for more information|
+|`400`|`ValidationError: personalisation address_line_1 is a required property`|`BadRequestError`|Ensure that your template has a field for the first line of the address, refer to [personalisation](#personalisation-required) for more information|
 |`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
-|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
-|`429`|`RateLimitError: Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds`|`RateLimitError`|Refer to [API rate limits](/ruby.html#api-rate-limits) for more information|
-|`429`|`TooManyRequestsError: Exceeded send limits (LIMIT NUMBER) for today`|`RateLimitError`|Refer to [service limits](/ruby.html#service-limits) for the limit number|
+|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
+|`429`|`RateLimitError: Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds`|`RateLimitError`|Refer to [API rate limits](#api-rate-limits) for more information|
+|`429`|`TooManyRequestsError: Exceeded send limits (LIMIT NUMBER) for today`|`RateLimitError`|Refer to [service limits](#service-limits) for the limit number|
 |`500`|`Exception: Internal server error`|`ServerError`|Notify was unable to process the request, resend your notification|
 
 ## Send a precompiled letter
@@ -394,7 +394,7 @@ A unique identifier you create. This reference identifies a single unique notifi
 
 #### pdf_file (required)
 
-The precompiled letter must be a PDF file which meets [the GOV.UK Notify PDF letter specification](https://docs.notifications.service.gov.uk/documentation/images/notify-pdf-letter-spec-v2.3.pdf).
+The precompiled letter must be a PDF file which meets [the GOV.UK Notify PDF letter specification](https://docs.notifications.service.gov.uk/documentation/images/notify-pdf-letter-spec-v2.4.pdf).
 
 ```ruby
 File.open("path/to/pdf_file", "rb") do |pdf_file|
@@ -409,7 +409,7 @@ You can choose first or second class postage for your precompiled letter. Set th
 
 ### Response
 
-If the request to the client is successful, the client returns a `Notifications::Client:ResponsePrecompiledLetter` object. In the example shown in the [Method section](/ruby.html#send-a-pre-compiled-letter-method), the object is named `precompiled_letter`.
+If the request to the client is successful, the client returns a `Notifications::Client:ResponsePrecompiledLetter` object. In the example shown in the [Method section](#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.
 
@@ -486,18 +486,13 @@ response = client.get_notification(id)
 
 #### id (required)
 
-The ID of the notification. You can find the notification ID in the response to the [original notification method call](/ruby.html#response).
-
-You can also find it in your [GOV.UK Notify Dashboard](https://www.notifications.service.gov.uk).
+The ID of the notification. You can find the notification ID in the response to the [original notification method call](#response).
 
-1. Sign into GOV.UK Notify and select __Dashboard__.
-1. Select either __emails sent__, __text messages sent__, or __letters sent__.
-1. Select the relevant notification.
-1. Copy the notification ID from the end of the page URL, for example `https://www.notifications.service.gov.uk/services/af90d4cb-ae88-4a7c-a197-5c30c7db423b/notification/ID`.
+You can also find it by signing in to [GOV.UK Notify](https://www.notifications.service.gov.uk) and going to the __API integration__ page.
 
 ### Response
 
-If the request to the client is successful, the client returns a `Notifications::Client::Notification` object. In the example shown in the [Method section](/ruby.html#get-the-status-of-one-message-method), the object is named `response`.
+If the request to the client is successful, the client returns a `Notifications::Client::Notification` object. In the example shown in the [Method section](#get-the-status-of-one-message-method), the object is named `response`.
 
 You can then call different methods on this object to return the requested information.
 
@@ -533,7 +528,7 @@ If the request is not successful, the client returns a `Notification::Client::Re
 |:---|:---|:---|:---|
 |`400`|`ValidationError: id is not a valid UUID`|`BadRequestError`|Check the notification ID|
 |`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
-|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
+|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
 |`404`|`NoResultFound: No result found`|`NotFoundError`|Check the notification ID. This error occurs if the notification is more than 7 days old.|
 
 ## Get the status of multiple messages
@@ -611,7 +606,7 @@ The client only returns notifications that are 7 days old or newer. If the notif
 
 ### Response
 
-If the request to the client is successful, the client returns a `Notifications::Client::NotificationsCollection` object. In the example shown in the [Method section](/ruby.html#get-the-status-of-multiple-messages-method), the object is named `response`.
+If the request to the client is successful, the client returns a `Notifications::Client::NotificationsCollection` object. In the example shown in the [Method section](#get-the-status-of-multiple-messages-method), the object is named `response`.
 
 You must then call either the `.links` method or the `.collection` method on this object.
 
@@ -656,7 +651,46 @@ If the request is not successful, the client returns a `Notifications::Client::R
 |`400`|`ValidationError: bad status is not one of [created, sending, sent, delivered, pending, failed, technical-failure, temporary-failure, permanent-failure, accepted, received]`|`BadRequestError`|Contact the GOV.UK Notify team|
 |`400`|`ValidationError: Template type is not one of [sms, email, letter]`|`BadRequestError`|Contact the GOV.UK Notify team|
 |`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
-|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
+|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
+
+## Get a PDF for a letter notification
+
+### Method
+
+This returns the pdf contents of a letter notification.
+
+```ruby
+pdf_file = client.get_pdf_for_letter(
+  'f33517ff-2a88-4f6e-b855-c550268ce08a' # notification id (required)
+)
+```
+
+### Arguments
+
+#### id (required)
+
+The ID of the notification. You can find the notification ID in the response to the [original notification method call](#get-the-status-of-one-message-response).
+
+You can also find it by signing in to [GOV.UK Notify](https://www.notifications.service.gov.uk) and going to the __API integration__ page.
+
+### Response
+
+If the request to the client is successful, the client will return a `string` containing the raw PDF data.
+
+### Error codes
+
+If the request is not successful, the client throws a `Notifications::Client::RequestError` and an error code.
+|error.code|error.message|class|How to fix|
+|:---|:---|:---|:---|
+|`400`|`ValidationError: id is not a valid UUID`|`BadRequestError`|Check the notification ID|
+|`400`|`PDFNotReadyError: PDF not available yet, try again later`|`BadRequestError`|Wait for the notification to finish processing. This usually takes a few seconds|
+|`400`|`BadRequestError: Document did not pass the virus scan`|`BadRequestError`|You cannot retrieve the contents of a letter notification that contains a virus|
+|`400`|`BadRequestError: PDF not available for letters in technical-failure`|`BadRequestError`|You cannot retrieve the contents of a letter notification in technical-failure|
+|`400`|`ValidationError: Notification is not a letter`|`BadRequestError`|Check that you are looking up the correct notification|
+|`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`BadRequestError`|Check your system clock|
+|`403`|`AuthError: Invalid token: signature, api token not found`|`BadRequestError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
+|`404`|`NoResultFound: No result found`|`BadRequestError`|Check the notification ID|
+
 
 # Get a template
 
@@ -682,7 +716,7 @@ The ID of the template. Sign into GOV.UK Notify and go to the __Templates__ page
 
 ### Response
 
-If the request to the client is successful, the client returns a `Notifications::Client::Template` object. In the example shown in the [Method section](/ruby.html#get-a-template-by-id-method), the object is named `response`.
+If the request to the client is successful, the client returns a `Notifications::Client::Template` object. In the example shown in the [Method section](#get-a-template-by-id-method), the object is named `response`.
 
 You can then call different methods on this object to return the requested information.
 
@@ -706,8 +740,8 @@ If the request is not successful, the client returns a `Notifications::Client::R
 |:---|:---|:---|:---|
 |`400`|`ValidationError: id is not a valid UUID`|`BadRequestError`|Check the notification ID|
 |`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
-|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
-|`404`|`NoResultFound: No Result Found`|`NotFoundError`|Check your [template ID](/ruby.html#get-a-template-by-id-arguments-id-required)|
+|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
+|`404`|`NoResultFound: No Result Found`|`NotFoundError`|Check your [template ID](#get-a-template-by-id-arguments-id-required)|
 
 ## Get a template by ID and version
 
@@ -733,7 +767,7 @@ The version number of the template.
 
 ### Response
 
-If the request to the client is successful, the client returns a `Notifications::Client::Template` object. In the example shown in the [Method section](/ruby.html#get-a-template-by-id-and-version-method), the object is named `response`.
+If the request to the client is successful, the client returns a `Notifications::Client::Template` object. In the example shown in the [Method section](#get-a-template-by-id-and-version-method), the object is named `response`.
 
 You can then call different methods on this object to return the requested information.
 
@@ -757,8 +791,8 @@ If the request is not successful, the client returns a `Notifications::Client::R
 |:---|:---|:---|:---|
 |`400`|`ValidationError: id is not a valid UUID`|`BadRequestError`|Check the notification ID|
 |`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
-|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
-|`404`|`NoResultFound: No Result Found`|`NotFoundError`|Check your [template ID](/ruby.html#get-a-template-by-id-and-version-arguments-id-required) and [version](/ruby.html#version-required)|
+|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
+|`404`|`NoResultFound: No Result Found`|`NotFoundError`|Check your [template ID](#get-a-template-by-id-and-version-arguments-id-required) and [version](#version-required)|
 
 ## Get all templates
 
@@ -785,7 +819,7 @@ If you do not use `type`, the client returns all templates. Otherwise you can fi
 
 ### Response
 
-If the request to the client is successful, the client returns a `Notifications::Client::TemplateCollection` object. In the example shown in the [Method section](/ruby.html#get-all-templates-method), the object is named `response`.
+If the request to the client is successful, the client returns a `Notifications::Client::TemplateCollection` object. In the example shown in the [Method section](#get-all-templates-method), the object is named `response`.
 
 You must then call the `.collection` method on this object to return an array of the required templates.
 
@@ -842,7 +876,7 @@ If a template has placeholder fields for personalised information such as name o
 ```ruby
 personalisation: {
   name: "John Smith",
-  ID: "300241",                      
+  ID: "300241",
 }
 ```
 
@@ -850,7 +884,7 @@ You can leave out this argument if a template does not have any placeholder fiel
 
 ### Response
 
-If the request to the client is successful, the client returns a `Notifications::Client::TemplatePreview` object. In the example shown in the [Method section](/ruby.html#generate-a-preview-template-method), the object is named `response`.
+If the request to the client is successful, the client returns a `Notifications::Client::TemplatePreview` object. In the example shown in the [Method section](#generate-a-preview-template-method), the object is named `response`.
 
 You can then call different methods on this object to return the requested information.
 
@@ -870,9 +904,9 @@ If the request is not successful, the client returns a `Notifications::Client::R
 |error.code|error.message|class|How to fix|
 |:---|:---|:---|:---|
 |`400`|`BadRequestError: Missing personalisation: [PERSONALISATION FIELD]`|`BadRequestError`|Check that the personalisation arguments in the method match the placeholder fields in the template|
-|`400`|`NoResultFound: No result found`|`BadRequestError`|Check the [template ID](/ruby.html#generate-a-preview-template-arguments-id-required)|
+|`400`|`NoResultFound: No result found`|`BadRequestError`|Check the [template ID](#generate-a-preview-template-arguments-id-required)|
 |`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
-|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
+|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
 
 # Get received text messages
 
@@ -880,11 +914,11 @@ This API call returns one page of up to 250 received text messages. You can get
 
 You can only get the status of messages that are 7 days old or newer.
 
-You can also set up [callbacks](/ruby.html#callbacks) for received text messages.
+You can also set up [callbacks](#callbacks) for received text messages.
 
 ## Enable received text messages
 
-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) to enable receiving text messages for your service.
+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/C0E1ADVPC) to enable receiving text messages for your service.
 
 ## Get a page of received text messages
 
@@ -917,7 +951,7 @@ The client only returns notifications that are 7 days old or newer. If the notif
 
 ### Response
 
-If the request to the client is successful, the client returns a `Notifications::Client::ReceivedTextCollection` object. In the example shown in the [Method section](/ruby.html#get-received-text-messages-method), the object is named `response`.
+If the request to the client is successful, the client returns a `Notifications::Client::ReceivedTextCollection` object. In the example shown in the [Method section](#get-received-text-messages-method), the object is named `response`.
 
 You must then call either the `.links` method or the `.collection` method on this object.
 
@@ -946,4 +980,4 @@ If the request is not successful, the client returns a `Notifications::Client::R
 |error.code|error.message|class|How to fix|
 |:---|:---|:---|:---|
 |`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
-|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
+|`403`|`AuthError: Invalid token: signature, api token not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|

data/Dockerfile

@@ -0,0 +1,13 @@
+FROM ruby:2.4-slim
+
+RUN \
+	echo "Install Debian packages" \
+	&& apt-get update \
+	&& apt-get install -y --no-install-recommends \
+		gcc \
+		make \
+		curl \
+		git \
+    gnupg
+
+WORKDIR /var/project

data/bin/test_client.rb

@@ -20,6 +20,7 @@ def main
   test_get_notification_by_id_endpoint(client, precompiled_letter_notification.id, 'precompiled_letter')
   test_get_all_notifications(client)
   test_get_received_texts
+  test_get_pdf_for_letter(client, letter_notification.id)
   p 'ruby client integration tests pass'
   exit 0
 end
@@ -205,6 +206,28 @@ def test_get_notification_by_id_endpoint(client, id, message_type)
   end
 end
 
+def test_get_pdf_for_letter(client, id)
+  response = nil
+
+  # try 15 times with 3 secs sleep between each attempt, to get the PDF
+  15.times do
+    begin
+      response = client.get_pdf_for_letter(id)
+    rescue Notifications::Client::BadRequestError
+      sleep(3)
+    end
+
+    if !response.nil?
+      break
+    end
+  end
+
+  unless !response.nil? && response.start_with?("%PDF-")
+    p "get_pdf_for_letter response for " + id + " is not a PDF: " + response.to_s
+    exit 1
+  end
+end
+
 def hash_key_should_not_be_nil(fields, obj, method_name)
   fields.each do |field|
     if obj.has_value?(:"#{field}")

data/docker/Dockerfile

@@ -1,4 +1,4 @@
-FROM ruby:2.3.1-slim
+FROM ruby:2.4-slim
 
 ARG HTTP_PROXY
 ARG HTTPS_PROXY
@@ -13,7 +13,6 @@ RUN \
 		make \
 		curl \
 		git \
-
 	&& echo "Clean up" \
 	&& rm -rf /var/lib/apt/lists/* /tmp/*
 

data/lib/notifications/client.rb

@@ -67,6 +67,14 @@ module Notifications
       )
     end
 
+    ##
+    # @param id [String]
+    # @see Notifications::Client::Speaker#get
+    # @return [String]
+    def get_pdf_for_letter(id)
+      speaker.get_pdf_for_letter(id)
+    end
+
     ##
     # @param id [String]
     # @see Notifications::Client::Speaker#get

data/lib/notifications/client/speaker.rb

@@ -118,6 +118,19 @@ module Notifications
         perform_request!(request)
       end
 
+      def get_pdf_for_letter(id)
+        path = "/v2/notifications/" << id << "/pdf"
+        request = Net::HTTP::Get.new(path, headers)
+
+        # can't use `perform_request!` because we're just returning raw binary data
+        response = open(request)
+        if response.is_a?(Net::HTTPClientError) || response.is_a?(Net::HTTPServerError)
+          raise build_error(response)
+        else
+          response.body
+        end
+      end
+
     private
 
       ##

data/lib/notifications/client/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: notifications-ruby-client
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 5.1.0
 platform: ruby
 authors:
 - Government Digital Service
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-07-02 00:00:00.000000000 Z
+date: 2019-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jwt
@@ -128,6 +128,7 @@ files:
 - CHANGELOG.md
 - CONTRIBUTING.md
 - DOCUMENTATION.md
+- Dockerfile
 - Gemfile
 - LICENSE
 - Makefile
@@ -173,8 +174,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Ruby client for GOV.UK Notifications API