zerobounce-sdk 3.0.0 → 3.1.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 +184 -17
- data/README.md +26 -13
- data/lib/zerobounce/api_key.rb +238 -7
- data/lib/zerobounce/api_urls.rb +53 -0
- data/lib/zerobounce/base_request.rb +199 -82
- data/lib/zerobounce/client.rb +12 -4
- data/lib/zerobounce/configuration.rb +19 -3
- data/lib/zerobounce/error.rb +19 -7
- data/lib/zerobounce/get_file_helper.rb +40 -27
- data/lib/zerobounce/http_transport.rb +229 -0
- data/lib/zerobounce/priority3.rb +187 -46
- data/lib/zerobounce/request.rb +25 -42
- data/lib/zerobounce/response_error.rb +27 -4
- data/lib/zerobounce/response_shape.rb +190 -0
- data/lib/zerobounce/strict_bool.rb +23 -0
- data/lib/zerobounce/strict_json.rb +165 -0
- data/lib/zerobounce/version.rb +1 -1
- data/lib/zerobounce/warmup.rb +155 -69
- data/lib/zerobounce.rb +138 -97
- metadata +5 -15
data/lib/zerobounce/warmup.rb
CHANGED
|
@@ -3,11 +3,15 @@
|
|
|
3
3
|
require 'date'
|
|
4
4
|
require 'erb'
|
|
5
5
|
require 'json'
|
|
6
|
-
require '
|
|
6
|
+
require 'zerobounce/http_transport'
|
|
7
7
|
|
|
8
|
+
require 'zerobounce/api_urls'
|
|
8
9
|
require 'zerobounce/api_key'
|
|
10
|
+
require 'zerobounce/strict_json'
|
|
9
11
|
require 'zerobounce/error'
|
|
12
|
+
require 'zerobounce/get_file_helper'
|
|
10
13
|
require 'zerobounce/response_error'
|
|
14
|
+
require 'zerobounce/strict_bool'
|
|
11
15
|
|
|
12
16
|
module Zerobounce
|
|
13
17
|
# Client for the ZeroBounce Warmup API
|
|
@@ -25,12 +29,20 @@ module Zerobounce
|
|
|
25
29
|
# payload that is not a JSON object - /seeds is an array, /seed-count a bare
|
|
26
30
|
# number - comes back as the parsed value itself.
|
|
27
31
|
class Warmup
|
|
32
|
+
include ApiKey::RefusesDump
|
|
33
|
+
|
|
28
34
|
DEFAULT_BASE_URL = 'https://warmup-api.zerobounce.net'
|
|
29
35
|
BASE_PATH = '/api/v1/warmup'
|
|
30
36
|
|
|
31
37
|
ONBOARDING_MODELS = %w[self_managed zb_managed].freeze
|
|
32
38
|
EMAIL_TYPES = %w[transactional newsletter marketing].freeze
|
|
33
39
|
|
|
40
|
+
# The documented email_content fields
|
|
41
|
+
# (https://www.zerobounce.net/docs/warmup-api/adding-a-sending-account).
|
|
42
|
+
EMAIL_CONTENT_FIELDS = %w[company_name company_website company_description types_of_emails example_email].freeze
|
|
43
|
+
# The documented managed_sending fields.
|
|
44
|
+
MANAGED_SENDING_FIELDS = %w[weekdays_only timezone timezone_offset warmup_start_date].freeze
|
|
45
|
+
|
|
34
46
|
# Required by the schema but always replaced with the key's own team.
|
|
35
47
|
ANY_TEAM_ID = 1
|
|
36
48
|
|
|
@@ -42,11 +54,9 @@ module Zerobounce
|
|
|
42
54
|
# A key with surrounding whitespace or control characters would be
|
|
43
55
|
# quoted, unredacted, in the HTTP library's own error.
|
|
44
56
|
ApiKey.check!(api_key)
|
|
45
|
-
|
|
46
|
-
raise ArgumentError, 'base_url must be an https:// URL'
|
|
47
|
-
end
|
|
57
|
+
ApiUrls.check!(base_url, 'base_url')
|
|
48
58
|
|
|
49
|
-
@api_key = api_key
|
|
59
|
+
@api_key = ApiKey::Secret.new(api_key)
|
|
50
60
|
root = base_url.to_s
|
|
51
61
|
root = root.chomp('/') while root.end_with?('/')
|
|
52
62
|
@root = "#{root}#{BASE_PATH}"
|
|
@@ -73,9 +83,14 @@ module Zerobounce
|
|
|
73
83
|
# Adds a from-address to warmup. POST /sending-accounts
|
|
74
84
|
#
|
|
75
85
|
# +self_managed+ runs your own mailbox and needs +engagement_rule_id+ 0-4.
|
|
76
|
-
# +zb_managed+ has ZeroBounce provision it and takes +email_content+
|
|
77
|
-
# +
|
|
78
|
-
#
|
|
86
|
+
# +zb_managed+ has ZeroBounce provision it and takes +email_content+
|
|
87
|
+
# (+company_name+, +company_website+, +company_description+,
|
|
88
|
+
# +types_of_emails+, +example_email+) and +managed_sending+
|
|
89
|
+
# (+weekdays_only+, +timezone+, +timezone_offset+ -11 to 14,
|
|
90
|
+
# +warmup_start_date+); a 200 means accepted, and the mailbox is
|
|
91
|
+
# provisioned afterwards. Other keys are not sent and draw a warning.
|
|
92
|
+
ADD_ACCOUNT_OPTIONS = %w[engagement_rule_id ignore_conflict email_content managed_sending].freeze
|
|
93
|
+
|
|
79
94
|
def add_sending_account(from_address, onboarding_model, **options)
|
|
80
95
|
require_value(from_address, 'from_address')
|
|
81
96
|
unless ONBOARDING_MODELS.include?(onboarding_model.to_s)
|
|
@@ -92,8 +107,16 @@ module Zerobounce
|
|
|
92
107
|
raise ArgumentError, 'email_content and managed_sending are for zb_managed'
|
|
93
108
|
end
|
|
94
109
|
end
|
|
95
|
-
|
|
96
|
-
|
|
110
|
+
extra = options.keys.map(&:to_s) - ADD_ACCOUNT_OPTIONS
|
|
111
|
+
unless extra.empty?
|
|
112
|
+
warn "Zerobounce::Warmup#add_sending_account: #{extra.join(', ')} " \
|
|
113
|
+
"#{extra.length == 1 ? 'is not an option' : 'are not options'} and not sent; " \
|
|
114
|
+
"the options are #{ADD_ACCOUNT_OPTIONS.join(', ')}"
|
|
115
|
+
end
|
|
116
|
+
unless options[:ignore_conflict].nil?
|
|
117
|
+
# Parsed strictly, as the client's boolean options are: 'false' is false.
|
|
118
|
+
body['ignore_conflict'] = StrictBool.parse(options[:ignore_conflict], 'ignore_conflict')
|
|
119
|
+
end
|
|
97
120
|
body['email_content'] = email_content_body(options[:email_content]) if options.key?(:email_content)
|
|
98
121
|
body['managed_sending'] = managed_sending_body(options[:managed_sending]) if options.key?(:managed_sending)
|
|
99
122
|
|
|
@@ -309,12 +332,17 @@ module Zerobounce
|
|
|
309
332
|
|
|
310
333
|
private
|
|
311
334
|
|
|
312
|
-
attr_reader :
|
|
335
|
+
attr_reader :root
|
|
336
|
+
|
|
337
|
+
def api_key
|
|
338
|
+
@api_key.value
|
|
339
|
+
end
|
|
313
340
|
|
|
314
341
|
# -- argument checks ----------------------------------------------------
|
|
315
342
|
|
|
316
343
|
def require_value(value, name)
|
|
317
344
|
raise ArgumentError, "#{name} is required" if value.nil? || value.to_s.strip.empty?
|
|
345
|
+
raise ArgumentError, "#{name} must be a string" unless value.is_a?(String)
|
|
318
346
|
|
|
319
347
|
value
|
|
320
348
|
end
|
|
@@ -330,7 +358,15 @@ module Zerobounce
|
|
|
330
358
|
# A date for the API: a Date/Time or a YYYY-MM-DD string.
|
|
331
359
|
def api_date(value, name)
|
|
332
360
|
return value.strftime('%Y-%m-%d') if value.respond_to?(:strftime)
|
|
333
|
-
|
|
361
|
+
|
|
362
|
+
if value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
|
|
363
|
+
begin
|
|
364
|
+
Date.strptime(value, '%Y-%m-%d')
|
|
365
|
+
return value
|
|
366
|
+
rescue ArgumentError
|
|
367
|
+
raise ArgumentError, "#{name} must be YYYY-MM-DD"
|
|
368
|
+
end
|
|
369
|
+
end
|
|
334
370
|
|
|
335
371
|
raise ArgumentError, "#{name} must be YYYY-MM-DD"
|
|
336
372
|
end
|
|
@@ -348,12 +384,33 @@ module Zerobounce
|
|
|
348
384
|
'important_pct' => important_pct, 'click_pct' => click_pct }
|
|
349
385
|
end
|
|
350
386
|
|
|
387
|
+
# The value of +key+ (a Symbol or String key) and whether it was given.
|
|
388
|
+
# Looked up with key? so a false value is kept.
|
|
389
|
+
def field(hash, key)
|
|
390
|
+
return [true, hash[key.to_sym]] if hash.key?(key.to_sym)
|
|
391
|
+
return [true, hash[key.to_s]] if hash.key?(key.to_s)
|
|
392
|
+
|
|
393
|
+
[false, nil]
|
|
394
|
+
end
|
|
395
|
+
|
|
396
|
+
# Keys that are not API fields are left out of the request, with a
|
|
397
|
+
# warning naming the documented fields, as unknown keys were always left
|
|
398
|
+
# out (silently, up to 3.0.1).
|
|
399
|
+
def warn_unknown(hash, known, name)
|
|
400
|
+
unknown = hash.keys.map(&:to_s).uniq - known
|
|
401
|
+
return if unknown.empty?
|
|
402
|
+
|
|
403
|
+
warn "Zerobounce::Warmup#add_sending_account: #{name} #{unknown.join(', ')} " \
|
|
404
|
+
"#{unknown.length == 1 ? 'is not an API field' : 'are not API fields'} and not sent; " \
|
|
405
|
+
"the fields are #{known.join(', ')}"
|
|
406
|
+
end
|
|
407
|
+
|
|
351
408
|
def email_content_body(content)
|
|
352
409
|
raise ArgumentError, 'email_content must be a Hash' unless content.is_a?(Hash)
|
|
353
410
|
|
|
354
411
|
body = {}
|
|
355
|
-
types = content
|
|
356
|
-
|
|
412
|
+
given, types = field(content, :types_of_emails)
|
|
413
|
+
if given && !types.nil?
|
|
357
414
|
Array(types).each do |kind|
|
|
358
415
|
unless EMAIL_TYPES.include?(kind.to_s)
|
|
359
416
|
raise ArgumentError, 'types_of_emails must be transactional, newsletter and/or marketing'
|
|
@@ -361,10 +418,15 @@ module Zerobounce
|
|
|
361
418
|
end
|
|
362
419
|
body['types_of_emails'] = Array(types).map(&:to_s)
|
|
363
420
|
end
|
|
364
|
-
%
|
|
365
|
-
value = content
|
|
366
|
-
body[key
|
|
421
|
+
%w[company_name company_website company_description example_email].each do |key|
|
|
422
|
+
given, value = field(content, key)
|
|
423
|
+
body[key] = value if given && !value.nil?
|
|
367
424
|
end
|
|
425
|
+
# Up to 3.0.1 the SDK took the website as "website", which the API does
|
|
426
|
+
# not read; it is still accepted and sent as company_website.
|
|
427
|
+
given, website = field(content, :website)
|
|
428
|
+
body['company_website'] = website if given && !website.nil? && !body.key?('company_website')
|
|
429
|
+
warn_unknown(content, EMAIL_CONTENT_FIELDS + %w[website], 'email_content')
|
|
368
430
|
body
|
|
369
431
|
end
|
|
370
432
|
|
|
@@ -372,26 +434,37 @@ module Zerobounce
|
|
|
372
434
|
raise ArgumentError, 'managed_sending must be a Hash' unless sending.is_a?(Hash)
|
|
373
435
|
|
|
374
436
|
body = {}
|
|
375
|
-
|
|
376
|
-
body['
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
437
|
+
given, weekdays = field(sending, :weekdays_only)
|
|
438
|
+
body['weekdays_only'] = StrictBool.parse(weekdays, 'weekdays_only') if given && !weekdays.nil?
|
|
439
|
+
given, timezone = field(sending, :timezone)
|
|
440
|
+
if given && !timezone.nil?
|
|
441
|
+
raise ArgumentError, 'timezone must be a String, e.g. Europe/Bucharest' unless timezone.is_a?(String)
|
|
442
|
+
|
|
443
|
+
body['timezone'] = timezone
|
|
444
|
+
end
|
|
445
|
+
given, offset = field(sending, :timezone_offset)
|
|
446
|
+
body['timezone_offset'] = timezone_offset(offset) if given && !offset.nil?
|
|
447
|
+
given, start = field(sending, :warmup_start_date)
|
|
448
|
+
body['warmup_start_date'] = api_date(start, 'warmup_start_date') if given && !start.nil?
|
|
449
|
+
warn_unknown(sending, MANAGED_SENDING_FIELDS, 'managed_sending')
|
|
381
450
|
body
|
|
382
451
|
end
|
|
383
452
|
|
|
453
|
+
# -11 to 14, whole or fractional hours (the docs' example sends 3.0).
|
|
454
|
+
def timezone_offset(value)
|
|
455
|
+
# NaN cannot be compared (between? raises), so it is refused first.
|
|
456
|
+
unless (value.is_a?(Integer) || (value.is_a?(Float) && value.finite?)) && value.between?(-11, 14)
|
|
457
|
+
raise ArgumentError, 'timezone_offset must be -11 to 14'
|
|
458
|
+
end
|
|
459
|
+
|
|
460
|
+
value
|
|
461
|
+
end
|
|
462
|
+
|
|
384
463
|
# -- transport ----------------------------------------------------------
|
|
385
464
|
|
|
386
465
|
# Replaces every form of a secret in a message with ***.
|
|
387
466
|
def redact(text, secrets = [])
|
|
388
|
-
|
|
389
|
-
([api_key] + secrets).each do |secret|
|
|
390
|
-
next if secret.nil? || secret.to_s.empty?
|
|
391
|
-
|
|
392
|
-
value = value.gsub(secret.to_s, '***').gsub(ERB::Util.url_encode(secret.to_s), '***')
|
|
393
|
-
end
|
|
394
|
-
value
|
|
467
|
+
ApiKey.redact(text, [api_key] + secrets)
|
|
395
468
|
end
|
|
396
469
|
|
|
397
470
|
def get(path, **params)
|
|
@@ -399,69 +472,82 @@ module Zerobounce
|
|
|
399
472
|
end
|
|
400
473
|
|
|
401
474
|
def send_request(method, path, params, body, secrets)
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
}
|
|
410
|
-
if body
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
response = e.response
|
|
417
|
-
status = response.respond_to?(:code) ? response.code : 0
|
|
475
|
+
# Re-checked on every send (the key goes in a header to this URL), outside
|
|
476
|
+
# the rescue below, so it is the caller's ArgumentError.
|
|
477
|
+
ApiUrls.check!("#{root}#{path}", 'base_url')
|
|
478
|
+
deliver(method, path, params, body, secrets)
|
|
479
|
+
end
|
|
480
|
+
|
|
481
|
+
def deliver(method, path, params, body, secrets)
|
|
482
|
+
headers = { 'API-Key' => api_key, 'Accept' => 'application/json' }
|
|
483
|
+
headers['Content-Type'] = 'application/json' if body
|
|
484
|
+
response = HttpTransport.execute(
|
|
485
|
+
method: method, url: "#{root}#{path}", query: params, headers: headers,
|
|
486
|
+
body: body&.to_json, redact: ->(text) { redact(text, secrets) }
|
|
487
|
+
)
|
|
488
|
+
status = response.code
|
|
418
489
|
if status >= 300 && status < 400
|
|
419
490
|
raise ApiResponseError.new(
|
|
420
491
|
'ZeroBounce returned a redirect, which this client does not follow.', status
|
|
421
|
-
)
|
|
492
|
+
), cause: nil
|
|
422
493
|
end
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
status, (response
|
|
427
|
-
),
|
|
428
|
-
),
|
|
429
|
-
|
|
494
|
+
if status >= 400
|
|
495
|
+
raise ApiResponseError.new(
|
|
496
|
+
redact(
|
|
497
|
+
ResponseError.message_from_parts(status, content_type_of(response), response.body.to_s), secrets
|
|
498
|
+
), status
|
|
499
|
+
), cause: nil
|
|
500
|
+
end
|
|
501
|
+
|
|
502
|
+
response
|
|
430
503
|
rescue ApiResponseError
|
|
431
504
|
raise
|
|
432
505
|
rescue StandardError => e
|
|
433
|
-
#
|
|
434
|
-
|
|
506
|
+
# Every failure is rebuilt as the SDK's error, status 0, with cause: nil:
|
|
507
|
+
# the original holds the URL and headers.
|
|
508
|
+
raise HttpTransport.failure(e, ->(text) { redact(text, secrets) }), cause: nil
|
|
435
509
|
end
|
|
436
510
|
|
|
437
511
|
# The JSON payload of a success, or nil for the documented empty successes
|
|
438
|
-
# (204, and an empty 200).
|
|
512
|
+
# (204, and an empty 200). Empty means zero bytes: a blank body (spaces,
|
|
513
|
+
# a newline) is not JSON and is an error with its status.
|
|
439
514
|
def json_request(method, path, params = {}, body = nil, secrets: [])
|
|
440
515
|
response = send_request(method, path, params, body, secrets)
|
|
441
516
|
text = response.body.to_s
|
|
442
|
-
return nil if response.code == 204 || text.
|
|
517
|
+
return nil if response.code == 204 || text.empty?
|
|
518
|
+
|
|
519
|
+
# A page (a proxy's "Access denied") is an error even when its body parses as JSON.
|
|
520
|
+
raise body_error(response, text, secrets), cause: nil if ResponseError.html?(text, content_type_of(response))
|
|
443
521
|
|
|
444
522
|
begin
|
|
445
|
-
|
|
523
|
+
StrictJson.parse(text)
|
|
446
524
|
rescue JSON::ParserError
|
|
447
|
-
raise
|
|
448
|
-
redact(
|
|
449
|
-
ResponseError.message_from_parts(
|
|
450
|
-
response.code, (response.headers[:content_type] || '').to_s, text
|
|
451
|
-
), secrets
|
|
452
|
-
), response.code
|
|
453
|
-
)
|
|
525
|
+
raise body_error(response, text, secrets), cause: nil # the parser's error quotes the body
|
|
454
526
|
end
|
|
455
527
|
end
|
|
456
528
|
|
|
457
|
-
|
|
529
|
+
def content_type_of(response)
|
|
530
|
+
(response.headers[:content_type] || '').to_s
|
|
531
|
+
end
|
|
532
|
+
|
|
533
|
+
# The error for a 2xx body that is not a JSON result, redacted.
|
|
534
|
+
def body_error(response, text, secrets)
|
|
535
|
+
ApiResponseError.new(
|
|
536
|
+
redact(ResponseError.message_from_parts(response.code, content_type_of(response), text), secrets),
|
|
537
|
+
response.code
|
|
538
|
+
)
|
|
539
|
+
end
|
|
540
|
+
|
|
541
|
+
# A CSV download, returned as text. An HTML page on a 200 (a proxy's
|
|
542
|
+
# "Access denied") is an error, not CSV.
|
|
458
543
|
def csv(path, **params)
|
|
459
544
|
response = send_request(:get, path, params, nil, [])
|
|
460
545
|
text = response.body.to_s
|
|
461
546
|
content_type = (response.headers[:content_type] || '').to_s
|
|
462
|
-
if text.strip.empty? ||
|
|
547
|
+
if GetFileHelper.strip_bom(text).strip.empty? || GetFileHelper.json_type?(content_type) ||
|
|
548
|
+
ResponseError.html?(text, content_type) || GetFileHelper.json_container?(text)
|
|
463
549
|
raise ApiResponseError.new(
|
|
464
|
-
redact(ResponseError.message_from_parts(response.code, content_type, text)),
|
|
550
|
+
redact(ResponseError.message_from_parts(response.code, content_type, GetFileHelper.strip_bom(text))),
|
|
465
551
|
response.code
|
|
466
552
|
)
|
|
467
553
|
end
|