notifications-ruby-client 3.1.0 → 4.0.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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +4 -0
- data/DOCUMENTATION.md +60 -61
- data/lib/notifications/client/request_error.rb +12 -8
- data/lib/notifications/client/version.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 3bb224294830c1d0d4c4d776597d7ce144ca14fb993500f432275188914ab4cb
|
|
4
|
+
data.tar.gz: 94b010994127fbb3bcea06a408ec33587b3dbef34b8eaf404f6ece05d26eaf5b
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 3c9f30f36f38523e8c36a784b9780f434f3cc798b9e6824dcbfa06dd2fcb96802dff67c9dd2affe7c294243929ab734da477aea8c89dc39aa9646aba8e815966
|
|
7
|
+
data.tar.gz: cd81acb5965952e29c3e5c26c6c5c6144b8a8eca2b60ee6e2a40e81789f839c2d7876dd7f2b492c157585e16f19f184b8bef0eb6aa23eb502bee89d53a2a6885
|
data/CHANGELOG.md
CHANGED
data/DOCUMENTATION.md
CHANGED
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
This documentation is for developers interested in using the GOV.UK Notify Ruby client to send emails, text messages or letters.
|
|
4
4
|
|
|
5
|
+
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.
|
|
6
|
+
|
|
5
7
|
# Set up the client
|
|
6
8
|
|
|
7
9
|
## Install the client
|
|
@@ -128,13 +130,13 @@ If the request is not successful, the client returns a `Notifications::Client::R
|
|
|
128
130
|
|
|
129
131
|
|error.code|error.message|class|How to fix|
|
|
130
132
|
|:---|:---|:---|:---|
|
|
131
|
-
|`400`|`
|
|
132
|
-
|`400`|`
|
|
133
|
-
|`403`|`
|
|
134
|
-
|`403`|`
|
|
135
|
-
|`429`|`
|
|
136
|
-
|`429`|`
|
|
137
|
-
|`500`|`
|
|
133
|
+
|`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)|
|
|
134
|
+
|`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)|
|
|
135
|
+
|`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
|
|
136
|
+
|`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|
|
|
137
|
+
|`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|
|
|
138
|
+
|`429`|`TooManyRequestsError: Exceeded send limits (LIMIT NUMBER) for today`|`ClientError`|Refer to [service limits](/ruby.html#service-limits) for the limit number|
|
|
139
|
+
|`500`|`Exception: Internal server error`|`ServerError`|Notify was unable to process the request, resend your notification|
|
|
138
140
|
|
|
139
141
|
## Send an email
|
|
140
142
|
|
|
@@ -263,17 +265,17 @@ If the request is not successful, the client returns a `Notifications::Client::R
|
|
|
263
265
|
|
|
264
266
|
|error.code|error.message|class|How to fix|
|
|
265
267
|
|:--- |:---|:---|:---|
|
|
266
|
-
|`400`|`
|
|
267
|
-
|`400`|`
|
|
268
|
-
|`400`|`
|
|
269
|
-
|`400`|`
|
|
270
|
-
|`400`|`
|
|
271
|
-
|`403`|`
|
|
272
|
-
|`403`|`
|
|
273
|
-
|`429`|`
|
|
274
|
-
|`429`|`
|
|
275
|
-
|`500`|`
|
|
276
|
-
|-|`
|
|
268
|
+
|`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)|
|
|
269
|
+
|`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)|
|
|
270
|
+
|`400`|`BadRequestError: Unsupported document type '{}'. Supported types are: {}`|`BadRequestError`|The document you upload must be a PDF file|
|
|
271
|
+
|`400`|`BadRequestError: Document didn't pass the virus scan`|`BadRequestError`|The document you upload must be virus free|
|
|
272
|
+
|`400`|`BadRequestError: Service is not allowed to send documents`|`BadRequestError`|Contact the GOV.UK Notify team|
|
|
273
|
+
|`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
|
|
274
|
+
|`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|
|
|
275
|
+
|`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|
|
|
276
|
+
|`429`|`TooManyRequestsError: Exceeded send limits (LIMIT NUMBER) for today`|`RateLimitError`|Refer to [service limits](/ruby.html#service-limits) for the limit number|
|
|
277
|
+
|`500`|`Exception: Internal server error`|`ServerError`|Notify was unable to process the request, resend your notification|
|
|
278
|
+
|-|`ArgumentError: Document is larger than 2MB")`|-|Document size was too large, upload a smaller document|
|
|
277
279
|
|
|
278
280
|
## Send a letter
|
|
279
281
|
|
|
@@ -369,17 +371,16 @@ If the request is not successful, the client returns a `Notifications::Client::R
|
|
|
369
371
|
|
|
370
372
|
|error.code|error.message|class|How to fix|
|
|
371
373
|
|:--- |:---|:---|:---|
|
|
372
|
-
|`400`|`
|
|
373
|
-
|`400`|`
|
|
374
|
-
|`400`|`
|
|
375
|
-
|`403`|`
|
|
376
|
-
|`403`|`
|
|
377
|
-
|`429`|`
|
|
378
|
-
|`429`|`
|
|
379
|
-
|`500`|`
|
|
374
|
+
|`400`|`BadRequestError: Cannot send letters with a team api key`|`BadRequestError`|Use the correct type of [API key](/ruby.html#api-keys)|
|
|
375
|
+
|`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)|
|
|
376
|
+
|`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|
|
|
377
|
+
|`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
|
|
378
|
+
|`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|
|
|
379
|
+
|`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|
|
|
380
|
+
|`429`|`TooManyRequestsError: Exceeded send limits (LIMIT NUMBER) for today`|`RateLimitError`|Refer to [service limits](/ruby.html#service-limits) for the limit number|
|
|
381
|
+
|`500`|`Exception: Internal server error`|`ServerError`|Notify was unable to process the request, resend your notification|
|
|
380
382
|
|
|
381
383
|
## Send a precompiled letter
|
|
382
|
-
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.
|
|
383
384
|
|
|
384
385
|
### Method
|
|
385
386
|
```ruby
|
|
@@ -393,7 +394,7 @@ A unique identifier you create. This reference identifies a single unique notifi
|
|
|
393
394
|
|
|
394
395
|
#### pdf_file (required)
|
|
395
396
|
|
|
396
|
-
The precompiled letter must be a PDF file.
|
|
397
|
+
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).
|
|
397
398
|
|
|
398
399
|
```ruby
|
|
399
400
|
File.open("path/to/pdf_file", "rb") do |pdf_file|
|
|
@@ -425,15 +426,13 @@ If the request is not successful, the client returns a `Notifications::Client::R
|
|
|
425
426
|
|
|
426
427
|
|error.status_code|error.message|class|How to fix|
|
|
427
428
|
|:---|:---|:---|:---|
|
|
428
|
-
|`400`|`
|
|
429
|
-
|`400`|`
|
|
430
|
-
|`400`|`
|
|
431
|
-
|`400`|`
|
|
432
|
-
|`400`|`
|
|
433
|
-
|`
|
|
434
|
-
|`
|
|
435
|
-
|`429`|`[{`<br>`"error": "RateLimitError",`<br>`"message": "Exceeded rate limit for key type live of 10 requests per 20 seconds"`<br>`}]`|`RateLimitError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
|
|
436
|
-
|`429`|`[{`<br>`"error": "TooManyRequestsError",`<br>`"message": "Exceeded send limits (50) for today"`<br>`}]`|`RateLimitError`|Refer to [service limits](#service-limits) for the limit number|
|
|
429
|
+
|`400`|`BadRequestError: Cannot send letters with a team api key`|`BadRequestError`|Use the correct type of [API key](#api-keys)|
|
|
430
|
+
|`400`|`BadRequestError: Letter content is not a valid PDF`|`BadRequestError`|PDF file format is required|
|
|
431
|
+
|`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)|
|
|
432
|
+
|`400`|`ValidationError: reference is a required property`|`BadRequestError`|Add a `reference` argument to the method call|
|
|
433
|
+
|`400`|`ValidationError: postage invalid. It must be either first or second.`|`BadRequestError`|Change the value of `postage` argument in the method call to either 'first' or 'second'|
|
|
434
|
+
|`429`|`RateLimitError: Exceeded rate limit for key type live of 10 requests per 20 seconds`|`RateLimitError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
|
|
435
|
+
|`429`|`TooManyRequestsError: Exceeded send limits (50) for today`|`RateLimitError`|Refer to [service limits](#service-limits) for the limit number|
|
|
437
436
|
|
|
438
437
|
# Get message status
|
|
439
438
|
|
|
@@ -471,7 +470,7 @@ You can only get the status of messages that are 7 days old or newer.
|
|
|
471
470
|
|:---|:---|
|
|
472
471
|
|Pending virus check|GOV.UK Notify has not completed a virus scan of the precompiled letter file.|
|
|
473
472
|
|Virus scan failed|GOV.UK Notify found a potential virus in the precompiled letter file.|
|
|
474
|
-
|Validation failed|Content in the precompiled letter file is outside the printable area.|
|
|
473
|
+
|Validation failed|Content in the precompiled letter file is outside the printable area. See the [GOV.UK Notify PDF letter specification](https://docs.notifications.service.gov.uk/documentation/images/notify-pdf-letter-spec-v2.3.pdf) for more information.|
|
|
475
474
|
|
|
476
475
|
## Get the status of one message
|
|
477
476
|
|
|
@@ -532,10 +531,10 @@ If the request is not successful, the client returns a `Notification::Client::Re
|
|
|
532
531
|
|
|
533
532
|
|error.code|error.message|class|How to fix|
|
|
534
533
|
|:---|:---|:---|:---|
|
|
535
|
-
|`400`|`
|
|
536
|
-
|`403`|`
|
|
537
|
-
|`403`|`
|
|
538
|
-
|`404`|`
|
|
534
|
+
|`400`|`ValidationError: id is not a valid UUID`|`BadRequestError`|Check the notification ID|
|
|
535
|
+
|`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
|
|
536
|
+
|`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|
|
|
537
|
+
|`404`|`NoResultFound: No result found`|`NotFoundError`|Check the notification ID. This error occurs if the notification is more than 7 days old.|
|
|
539
538
|
|
|
540
539
|
## Get the status of multiple messages
|
|
541
540
|
|
|
@@ -654,10 +653,10 @@ If the request is not successful, the client returns a `Notifications::Client::R
|
|
|
654
653
|
|
|
655
654
|
|error.code|error.message|class|How to fix|
|
|
656
655
|
|:---|:---|:---|:---|
|
|
657
|
-
|`400`|`
|
|
658
|
-
|`400`|`
|
|
659
|
-
|`403`|`
|
|
660
|
-
|`403`|`
|
|
656
|
+
|`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|
|
|
657
|
+
|`400`|`ValidationError: Template type is not one of [sms, email, letter]`|`BadRequestError`|Contact the GOV.UK Notify team|
|
|
658
|
+
|`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
|
|
659
|
+
|`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|
|
|
661
660
|
|
|
662
661
|
# Get a template
|
|
663
662
|
|
|
@@ -705,10 +704,10 @@ If the request is not successful, the client returns a `Notifications::Client::R
|
|
|
705
704
|
|
|
706
705
|
|error.code|error.message|class|How to fix|
|
|
707
706
|
|:---|:---|:---|:---|
|
|
708
|
-
|`400`|`
|
|
709
|
-
|`403`|`
|
|
710
|
-
|`403`|`
|
|
711
|
-
|`404`|`
|
|
707
|
+
|`400`|`ValidationError: id is not a valid UUID`|`BadRequestError`|Check the notification ID|
|
|
708
|
+
|`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
|
|
709
|
+
|`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|
|
|
710
|
+
|`404`|`NoResultFound: No Result Found`|`NotFoundError`|Check your [template ID](/ruby.html#get-a-template-by-id-arguments-id-required)|
|
|
712
711
|
|
|
713
712
|
## Get a template by ID and version
|
|
714
713
|
|
|
@@ -756,10 +755,10 @@ If the request is not successful, the client returns a `Notifications::Client::R
|
|
|
756
755
|
|
|
757
756
|
|error.code|error.message|class|How to fix|
|
|
758
757
|
|:---|:---|:---|:---|
|
|
759
|
-
|`400`|`
|
|
760
|
-
|`403`|`
|
|
761
|
-
|`403`|`
|
|
762
|
-
|`404`|`
|
|
758
|
+
|`400`|`ValidationError: id is not a valid UUID`|`BadRequestError`|Check the notification ID|
|
|
759
|
+
|`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
|
|
760
|
+
|`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|
|
|
761
|
+
|`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)|
|
|
763
762
|
|
|
764
763
|
## Get all templates
|
|
765
764
|
|
|
@@ -812,7 +811,7 @@ If the request is not successful, the client returns a `Notifications::Client::R
|
|
|
812
811
|
|
|
813
812
|
|error.code|error.message|class|How to fix|
|
|
814
813
|
|:---|:---|:---|:---|
|
|
815
|
-
|`400`|`
|
|
814
|
+
|`400`|`ValidationError: Template type is not one of [sms, email, letter]`|`BadRequestError`|Contact the Notify team|
|
|
816
815
|
|
|
817
816
|
## Generate a preview template
|
|
818
817
|
|
|
@@ -870,10 +869,10 @@ If the request is not successful, the client returns a `Notifications::Client::R
|
|
|
870
869
|
|
|
871
870
|
|error.code|error.message|class|How to fix|
|
|
872
871
|
|:---|:---|:---|:---|
|
|
873
|
-
|`400`|`
|
|
874
|
-
|`400`|`
|
|
875
|
-
|`403`|`
|
|
876
|
-
|`403`|`
|
|
872
|
+
|`400`|`BadRequestError: Missing personalisation: [PERSONALISATION FIELD]`|`BadRequestError`|Check that the personalisation arguments in the method match the placeholder fields in the template|
|
|
873
|
+
|`400`|`NoResultFound: No result found`|`BadRequestError`|Check the [template ID](/ruby.html#generate-a-preview-template-arguments-id-required)|
|
|
874
|
+
|`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
|
|
875
|
+
|`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|
|
|
877
876
|
|
|
878
877
|
# Get received text messages
|
|
879
878
|
|
|
@@ -946,5 +945,5 @@ If the request is not successful, the client returns a `Notifications::Client::R
|
|
|
946
945
|
|
|
947
946
|
|error.code|error.message|class|How to fix|
|
|
948
947
|
|:---|:---|:---|:---|
|
|
949
|
-
|`403`|`
|
|
950
|
-
|`403`|`
|
|
948
|
+
|`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
|
|
949
|
+
|`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|
|
|
@@ -1,22 +1,26 @@
|
|
|
1
1
|
module Notifications
|
|
2
2
|
class Client
|
|
3
3
|
class RequestError < StandardError
|
|
4
|
-
attr_reader :code, :
|
|
4
|
+
attr_reader :code, :body
|
|
5
5
|
|
|
6
6
|
def initialize(response)
|
|
7
7
|
@code = response.code
|
|
8
|
-
@
|
|
8
|
+
@body = parse_body(response.body)
|
|
9
9
|
end
|
|
10
10
|
|
|
11
|
-
def
|
|
12
|
-
|
|
13
|
-
end
|
|
14
|
-
|
|
15
|
-
def message_from(body)
|
|
16
|
-
JSON.parse(body).fetch('errors')
|
|
11
|
+
def parse_body(body)
|
|
12
|
+
JSON.parse(body)
|
|
17
13
|
rescue JSON::ParserError
|
|
18
14
|
body
|
|
19
15
|
end
|
|
16
|
+
|
|
17
|
+
def message
|
|
18
|
+
return body if body.is_a?(String)
|
|
19
|
+
|
|
20
|
+
error_messages = body.fetch('errors')
|
|
21
|
+
.map { |e| "#{e.fetch('error')}: #{e.fetch('message')}" }
|
|
22
|
+
error_messages.join(", ")
|
|
23
|
+
end
|
|
20
24
|
end
|
|
21
25
|
|
|
22
26
|
class ClientError < RequestError; end
|
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: notifications-ruby-client
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version:
|
|
4
|
+
version: 4.0.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Government Digital Service
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: exe
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2019-02
|
|
11
|
+
date: 2019-07-02 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: jwt
|