notifications-ruby-client 3.1.0 → 4.0.0
Sign up to get free protection for your applications and to get access to all the features.
- 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
|