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.
@@ -3,11 +3,15 @@
3
3
  require 'date'
4
4
  require 'erb'
5
5
  require 'json'
6
- require 'rest-client'
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
- unless base_url.to_s.downcase.start_with?('https://')
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+ and
77
- # +managed_sending+; a 200 means accepted, and the mailbox is provisioned
78
- # afterwards.
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
- body['ignore_conflict'] = !options[:ignore_conflict].nil? && options[:ignore_conflict] ? true : false if
96
- options.key?(:ignore_conflict)
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 :api_key, :root
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
- return value if value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
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[:types_of_emails] || content['types_of_emails']
356
- unless types.nil?
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
- %i[industry company_name website].each do |key|
365
- value = content[key] || content[key.to_s]
366
- body[key.to_s] = value unless value.nil?
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
- offset = sending[:timezone_offset] || sending['timezone_offset']
376
- body['timezone_offset'] = in_range(offset, -11, 14, 'timezone_offset') unless offset.nil?
377
- start = sending[:warmup_start_date] || sending['warmup_start_date']
378
- body['warmup_start_date'] = api_date(start, 'warmup_start_date') unless start.nil?
379
- limit = sending[:daily_limit] || sending['daily_limit']
380
- body['daily_limit'] = limit unless limit.nil?
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
- value = text.to_s
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
- url = "#{root}#{path}"
403
- options = {
404
- method: method,
405
- url: url,
406
- timeout: 120,
407
- max_redirects: 0,
408
- headers: { 'API-Key' => api_key, accept: :json, params: params }
409
- }
410
- if body
411
- options[:payload] = body.to_json
412
- options[:headers][:content_type] = :json
413
- end
414
- RestClient::Request.execute(**options)
415
- rescue RestClient::ExceptionWithResponse => e
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
- raise ApiResponseError.new(
424
- redact(
425
- ResponseError.message_from_parts(
426
- status, (response.headers[:content_type] || '').to_s, response.body.to_s
427
- ), secrets
428
- ), status
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
- # Rebuilt rather than re-raised: the original holds the URL and headers.
434
- raise e.class, redact(e.message, secrets)
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.strip.empty?
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
- JSON.parse(text, quirks_mode: true)
523
+ StrictJson.parse(text)
446
524
  rescue JSON::ParserError
447
- raise ApiResponseError.new(
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
- # A CSV download, returned as text.
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? || content_type.downcase.include?('application/json')
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