RubyGems - notifications-ruby-client - Versions diffs - 2.7.0 → 2.8.0 - Mend

notifications-ruby-client 2.7.0 → 2.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

checksums.yaml +5 -5
data/.github/PULL_REQUEST_TEMPLATE.md +1 -1
data/CHANGELOG.md +5 -0
data/CONTRIBUTING.md +39 -0
data/DOCUMENTATION.md +544 -529
data/README.md +6 -812
data/bin/test_client.rb +1 -0
data/lib/notifications/client/response_template.rb +1 -0
data/lib/notifications/client/version.rb +1 -1
metadata +4 -3

data/README.md CHANGED Viewed

@@ -1,816 +1,10 @@
 # GOV.UK Notify Ruby client
-This documentation is for developers interested in using this Ruby client to integrate their government service with GOV.UK Notify.
+Use this client to send emails, text messages and letters using the [GOV.UK Notify](https://www.notifications.service.gov.uk) API.
-[![Gem Version](https://badge.fury.io/rb/notifications-ruby-client.svg)](https://badge.fury.io/rb/notifications-ruby-client)
+Useful links:
-## Table of Contents
-* [Installation](#installation)
-* [Getting started](#getting-started)
-* [Send messages](#send-messages)
-* [Get the status of one message](#get-the-status-of-one-message)
-* [Get the status of all messages](#get-the-status-of-all-messages)
-* [Get a template by ID](#get-a-template-by-id)
-* [Get a template by ID and version](#get-a-template-by-id-and-version)
-* [Get all templates](#get-all-templates)
-* [Generate a preview template](#generate-a-preview-template)
-* [Get received texts](#get-received-texts)
-## Installation
-Prior to usage an account must be created through the Notify admin console. This will allow access to the API credentials you application.
-You can then install the gem or require it in your application.
-```
-gem install 'notifications-ruby-client'
-```
-## Getting started
-```ruby
-require 'notifications/client'
-client = Notifications::Client.new(api_key)
-```
-Generate an API key by logging in to GOV.UK Notify [GOV.UK Notify](https://www.notifications.service.gov.uk) and going to the **API integration** page.
-## Send messages
-### Text message
-#### Method
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```ruby
-sms = client.send_sms(
-  phone_number: number,
-  template_id: template_id,
-  personalisation: {
-    name: "name",
-    year: "2016",
-  },
-  reference: "your_reference_string",
-  sms_sender_id: sms_sender_id
-) # => Notifications::Client::ResponseNotification
-```
-</details>
-#### Response
-If the request is successful, a `Notifications::Client:ResponseNotification` is returned.
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```ruby
-sms => Notifications::Client::ResponseNotification
-sms.id         # => uuid for the notification
-sms.reference  # => Reference string you supplied in the request
-sms.content    # => Hash containing body => the message sent to the recipient, with placeholders replaced.
-               #                    from_number => the sms sender number of your service found **Settings** page
-sms.template   # => Hash containing id => id of the template
-               #                    version => version of the template
-               #                    uri => url of the template
-sms.uri        # => URL of the notification
-```
-Otherwise the client will raise a `Notifications::Client::RequestError`:
-|`error.code`|`error.message`|
-|:---|:---|
-|`429`|`[{`<br>`"error": "RateLimitError",`<br>`"message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"`<br>`}]`|
-|`429`|`[{`<br>`"error": "TooManyRequestsError",`<br>`"message": "Exceeded send limits (50) for today"`<br>`}]`|
-|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can"t send to this recipient using a team-only API key"`<br>`]}`|
-|`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>`}]`|
-</details>
-#### Arguments
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-##### `phone_number`
-The phone number of the recipient, only required for sms notifications.
-##### `template_id`
-Find by clicking **API info** for the template you want to send.
-##### `reference`
-An optional identifier you generate. The `reference` can be used as a unique reference for the notification. Because Notify does not require this reference to be unique you could also use this reference to identify a batch or group of notifications.
-You can omit this argument if you do not require a reference for the notification.
-##### `personalisation`
-If a template has placeholders, you need to provide their values, for example:
-```python
-personalisation={
-    'first_name': 'Amala',
-    'reference_number': '300241',
-}
-```
-##### `sms_sender_id`
-Optional. Specifies the identifier of the sms sender to set for the notification. The identifiers are found in your service Settings, when you 'Manage' your 'Text message sender'.
-If you omit this argument your default sms sender will be set for the notification.
-</details>
-### Email
-#### Method
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```ruby
-email = client.send_email(
-  email_address: email_address,
-  template_id: template_id,
-  personalisation: {
-    name: "name",
-    year: "2016"
-  },
-  reference: "your_reference_string",
-  email_reply_to_id: email_reply_to_id
-) # => Notifications::Client::ResponseNotification
-```
-</details>
-#### Response
-If the request is successful, a `Notifications::Client:ResponseNotification` is returned.
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```ruby
-email => Notifications::Client::ResponseNotification
-email.id         # => uuid for the notification
-email.reference  # => Reference string you supplied in the request
-email.content    # => Hash containing body => the message sent to the recipient, with placeholders replaced.
-                 #                    subject => subject of the message sent to the recipient, with placeholders replaced.
-                 #                    from_email => the from email of your service found **Settings** page
-email.template   # => Hash containing id => id of the template
-                 #                    version => version of the template
-                 #                    uri => url of the template
-email.uri        # => URL of the notification
-```
-Otherwise the client will raise a `Notifications::Client::RequestError`:
-|`error.code`|`error.message`|
-|:---|:---|
-|`429`|`[{`<br>`"error": "RateLimitError",`<br>`"message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"`<br>`}]`|
-|`429`|`[{`<br>`"error": "TooManyRequestsError",`<br>`"message": "Exceeded send limits (50) for today"`<br>`}]`|
-|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can"t send to this recipient using a team-only API key"`<br>`]}`|
-|`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>`}]`|
-</details>
-#### Arguments
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-##### `email_address`
-The email address of the recipient, only required for email notifications.
-##### `template_id`
-Find by clicking **API info** for the template you want to send.
-##### `reference`
-An optional identifier you generate. The `reference` can be used as a unique reference for the notification. Because Notify does not require this reference to be unique you could also use this reference to identify a batch or group of notifications.
-You can omit this argument if you do not require a reference for the notification.
-##### `email_reply_to_id`
-Optional. Specifies the identifier of the email reply-to address to set for the notification. The identifiers are found in your service Settings, when you 'Manage' your 'Email reply to addresses'.
-If you omit this argument your default email reply-to address will be set for the notification.
-##### `personalisation`
-If a template has placeholders, you need to provide their values, for example:
-```python
-personalisation={
-    'first_name': 'Amala',
-    'application_number': '300241',
-}
-```
-</details>
-### Letter
-#### Method
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```ruby
-letter = client.send_letter(
-  template_id: template_id,
-  personalisation: {
-    address_line_1: 'Her Majesty The Queen',  # required
-    address_line_2: 'Buckingham Palace', # required
-    address_line_3: 'London',
-    postcode: 'SW1 1AA',  # required
-    ... # any other personalisation found in your template
-  },
-  reference: "your_reference_string"
-) # => Notifications::Client::ResponseNotification
-```
-</details>
-#### Response
-If the request is successful, a `Notifications::Client:ResponseNotification` is returned.
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```ruby
-letter => Notifications::Client::ResponseNotification
-letter.id           # => uuid for the notification
-letter.reference    # => Reference string you supplied in the request
-letter.content      # => Hash containing body => the body of the letter sent to the recipient, with placeholders replaced
-                    #                    subject => the main heading of the letter
-letter.template     # => Hash containing id => id of the template
-                    #                    version => version of the template
-                    #                    uri => url of the template
-letter.uri          # => URL of the notification
-```
-|`error.code`|`error.message`|
-|:---|:---|
-|`429`|`[{`<br>`"error": "RateLimitError",`<br>`"message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"`<br>`}]`|
-|`429`|`[{`<br>`"error": "TooManyRequestsError",`<br>`"message": "Exceeded send limits (50) for today"`<br>`}]`|
-|`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can"t send to this recipient using a team-only API key"`<br>`]}`|
-|`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>`}]`|
-|`400`|`[{`<br>`"error": "ValidationError",`<br>`"message": "personalisation address_line_1 is a required property"`<br>`}]`|
-</details>
-#### Arguments
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-#### `template_id`
-Find by clicking **API info** for the template you want to send.
-#### `reference`
-An optional identifier you generate. The `reference` can be used as a unique reference for the notification. Because Notify does not require this reference to be unique you could also use this reference to identify a batch or group of notifications.
-You can omit this argument if you do not require a reference for the notification.
-#### `personalisation`
-If the template has placeholders you need to provide their values as a Hash, for example:
-```ruby
-  personalisation: {
-    'first_name' => 'Amala',
-    'reference_number' => '300241',
-  }
-```
-You can omit this argument if the template does not contain placeholders and is for email or sms.
-#### `personalisation` (for letters)
-If you are sending a letter, you will need to provide the letter fields in the format `"address_line_#"`, for example:
-```ruby
-personalisation: {
-    'address_line_1' => 'The Occupier',
-    'address_line_2' => '123 High Street',
-    'address_line_3' => 'London',
-    'postcode' => 'SW14 6BH',
-    'first_name' => 'Amala',
-    'reference_number' => '300241',
-}
-```
-The fields `address_line_1`, `address_line_2` and `postcode` are required.
-</details>
-## Get the status of one message
-#### Method
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```ruby
-notification = client.get_notification(id) # => Notifications::Client::Notification
-```
-</details>
-#### Response
-If successful a `Notifications::Client::Notification` is returned.
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```ruby
-notification.id                     # => uuid for the notification
-notification.reference              # => reference string you supplied in the request
-notification.email_address          # => email address of the recipient (for email notifications)
-notification.phone_number           # => phone number of the recipient (for SMS notifications)
-notification.line_1                 # => line 1 of the address of the recipient (for letter notifications)
-notification.line_2                 # => line 2 of the address of the recipient (for letter notifications)
-notification.line_3                 # => line 3 of the address of the recipient (for letter notifications)
-notification.line_4                 # => line 4 of the address of the recipient (for letter notifications)
-notification.line_5                 # => line 5 of the address of the recipient (for letter notifications)
-notification.line_6                 # => line 6 of the address of the recipient (for letter notifications)
-notification.postcode               # => postcode of the recipient (for letter notifications)
-notification.type                   # => type of notification sent (sms, email or letter)
-notification.status                 # => notification status (sending / delivered / permanent-failure / temporary-failure / technical-failure)
-notification.template               # => uuid of the template
-notification.body                   # => body of the notification
-notification.subject                # => the subject of the notification (email notifications only)
-notification.sent_at                # => date and time the notification was sent to the provider
-notification.created_at             # => date and time the notification was created
-notification.completed_at           # => date and time the notification was delivered or failed
-notification.created_by_name        # => name of the person who sent the notification if sent manually
-```
-Otherwise a `Notification::Client::RequestError` is raised
-|`error.code`|`error.message`|
-|:---|:---|
-|`404`|`[{`<br>`"error": "NoResultFound",`<br>`"message": "No result found"`<br>`}]`|
-|`404`|`[{`<br>`"error": "ValidationError",`<br>`"message": "is not a valid UUID"`<br>`}]`|
-</details>
-#### Arguments
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-##### `id`
-The ID of the notification.
-</details>
-## Get the status of all messages
-#### Method
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```ruby
-# See section below for a description of the arguments.
-# This will return 250 of the most recent messages over the last 7 days, if `older_than` is omitted.
-# The following 250 messages can be accessed through the hash `notifications.links["next"]`
-args = {
-  'template_type' => 'sms',
-  'status' => 'failed',
-  'reference' => 'your reference string'
-  'older_than' => 'e194efd1-c34d-49c9-9915-e4267e01e92e' # => Notifications::Client::Notification
-}
-notifications = client.get_notifications(args)
-```
-</details>
-#### Response
-If the request is successful a `Notifications::Client::NotificationsCollection` is returned.
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```ruby
-notifications.links # => Hash containing current => "/notifications?template_type=sms&status=delivered"
-                    #                    next => "/notifications?older_than=last_id_in_list&template_type=sms&status=delivered"
-notifications.collection # => [] (array of notification objects)
-```
-Otherwise the client will raise a `Notifications::Client::RequestError`:
-|`error.status_code`|`error.message`|
-|:---|:---|
-|`400`|`[{`<br>`"error": "ValidationError",`<br>`"message": "bad status is not one of [created, sending, delivered, pending, failed, technical-failure, temporary-failure, permanent-failure]"`<br>`}]`|
-|`400`|`[{`<br>`"error": "ValidationError",`<br>`"message": "Apple is not one of [sms, email, letter]"`<br>`}]`|
-</details>
-#### Arguments
-Omit the argument Hash if you do not want to filter the results.
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-##### `template_type`
-If omitted all messages are returned. Otherwise you can filter by:
-* `email`
-* `sms`
-* `letter`
-You can omit this argument to ignore the filter.
-##### `status`
-You can filter by:
-* `sending` - the message is queued to be sent by the provider.
-* `delivered` - the message was successfully delivered.
-* `failed` - this will return all failure statuses `permanent-failure`, `temporary-failure` and `technical-failure`.
-* `permanent-failure` - the provider was unable to deliver message, email or phone number does not exist; remove this recipient from your list.
-* `temporary-failure` - the provider was unable to deliver message, email box was full or the phone was turned off; you can try to send the message again.
-* `technical-failure` - Notify had a technical failure; you can try to send the message again.
-You can omit this argument to ignore the filter.
-##### `reference`
-This is the `reference` you gave at the time of sending the notification. The `reference` can be a unique identifier for the notification or an identifier for a batch of notifications.
-You can omit this argument to ignore the filter.
-##### `older_than`
-You can get the notifications older than a given `Notification.id`.
-You can omit this argument to ignore this filter.
-</details>
-## Get a template by ID
-#### Method
-This will return the latest version of the template. Use [getTemplateVersion](#get-a-template-by-id-and-version) to retrieve a specific template version.
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```ruby
-template = client.get_template_by_id(id)
-```
-</details>
-#### Response
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```Ruby
-template.id         # => uuid for the template
-template.type       # => type of template one of email|sms|letter
-template.created_at # => date and time the template was created
-template.updated_at # => date and time the template was last updated, may be null if version 1
-template.created_by # => email address of the person that created the template
-template.version    # => version of the template
-template.body       # => content of the template
-template.subject    # => subject for email templates, will be empty for other template types
-```
-Otherwise the client will raise a `Notifications::Client::RequestError`.
-</details>
-#### Arguments
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-|`error.code`|`error.message`|
-|:---|:---|
-|`404`|`[{`<br>`"error": "NoResultFound",`<br>`"message": "No result found"`<br>`}]`|
-|`404`|`[{`<br>`"error": "ValidationError",`<br>`"message": "is is not a valid UUID"`<br>`}]`|
-##### `id`
-The template id is visible on the template page in the application.
-</details>
-## Get a template by ID and version
-#### Method
-This will return the template for the given id and version.
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```ruby
-Template template = client.get_template_version(id, version)
-```
-</details>
-#### Response
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```Ruby
-template.id         # => uuid for the template
-template.type       # => type of template one of email|sms|letter
-template.created_at # => date and time the template was created
-template.updated_at # => date and time the template was last updated, may be null if version 1
-template.created_by # => email address of the person that created the template
-template.version    # => version of the template
-template.body       # => content of the template
-template.subject    # => subject for email templates, will be empty for other template types
-```
-Otherwise the client will raise a `Notifications::Client::RequestError`.
-|`error.code`|`error.message`|
-|:---|:---|
-|`404`|`[{`<br>`"error": "NoResultFound",`<br>`"message": "No result found"`<br>`}]`|
-|`404`|`[{`<br>`"error": "ValidationError",`<br>`"message": "is is not a valid UUID"`<br>`}]`|
-</details>
-#### Arguments
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-#### `id`
-The template id is visible on the template page in the application.
-#### `version`
-A history of the template is kept. There is a link to `See previous versions` on the template page in the application.
-</details>
-## Get all templates
-#### Method
-This will return the latest version of each template for your service.
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```ruby
-args = {
-  'template_type' => 'sms'
-}
-templates = client.get_all_templates(args)
-```
-</details>
-#### Response
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```ruby
-    TemplateCollection templates;
-```
-If the response is successful, a TemplateCollection is returned.
-If no templates exist for a template type or there no templates for a service, the templates list will be empty.
-Otherwise the client will raise a `Notifications::Client::RequestError`.
-</details>
-#### Arguments
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-##### `template_type`
-If omitted all templates are returned. Otherwise you can filter by:
-* `email`
-* `sms`
-* `letter`
-</details>
-## Generate a preview template
-#### Method
-This will return the contents of a template with the placeholders replaced with the given personalisation.
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```ruby
-templatePreview = client.generate_template_preview(id,
-                                                  personalisation: {
-                                                      name: "name",
-                                                      year: "2016",
-                                                    })
-```
-</details>
-#### Response
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```Ruby
-template.id         # => uuid for the template
-template.version    # => version of the template
-template.body       # => content of the template
-template.subject    # => subject for email templates, will be empty for other template types
-template.type       # => type of notification the template is for (sms, email or letter)
-```
-Otherwise a `Notifications::Client::RequestError` is thrown.
-|`error.code`|`error.message`|
-|:---|:---|
-|`404`|`[{`<br>`"error": "NoResultFound",`<br>`"message": "No result found"`<br>`}]`|
-|`404`|`[{`<br>`"error": "ValidationError",`<br>`"message": "is is not a valid UUID"`<br>`}]`|
-</details>
-#### Arguments
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-##### `id`
-The template id is visible on the template page in the application.
-##### `personalisation`
-If a template has placeholders, you need to provide their values. `personalisation` can be an empty or null in which case no placeholders are provided for the notification.
-</details>
-## Get received texts
-#### Method
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-```ruby
-# See section below for a description of the arguments.
-# This will return 250 of the most recent messages over the last 7 days, if `older_than` is omitted.
-# The following 250 messages can be accessed through the hash `received_texts.links["next"]`
-args = {
-  'older_than' => 'e194efd1-c34d-49c9-9915-e4267e01e92e' # => Notifications::Client::ReceivedText
-}
-received_texts = client.get_received_texts(args)
-```
-</details>
-#### Response
-If the request is successful a `Notifications::Client::ReceivedTextCollection` is returned.
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-`ReceivedTextCollection` -
-```ruby
-received_texts.links # => Hash containing current => "/v2/received-text-messages"
-                     #                    next => "/v2/received-text-messages?older_than=last_id_in_list"
-received_texts.collection # => [] (array of ReceivedText objects)
-```
-`ReceivedText` -
-```ruby
-received_text.id            # => uuid for the received text
-received_text.created_at    # => created_at of the received text
-received_text.content       # => content of the received text
-received_text.notify_number # => number received text was sent to
-received_text.service_id    # => service id of the received text
-received_text.user_number   # => number received text was sent from
-```
-</details>
-#### Arguments
-Omit the argument Hash if you do not want to filter the results.
-<details>
-<summary>
-Click here to expand for more information.
-</summary>
-##### `older_than`
-You can get the notifications older than a given `received_text.id`.
-You can omit this argument to ignore this filter.
-</details>
+- [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)