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.
data/lib/zerobounce.rb CHANGED
@@ -16,6 +16,7 @@ require 'zerobounce/validate_sub_status'
16
16
  require 'zerobounce/request'
17
17
  require 'zerobounce/configuration'
18
18
  require 'zerobounce/api_urls'
19
+ require 'zerobounce/response_shape'
19
20
  require 'zerobounce/priority3'
20
21
  require 'zerobounce/warmup'
21
22
 
@@ -95,18 +96,15 @@ module Zerobounce
95
96
  # }
96
97
  def validate(email, ip_address=nil, timeout: nil, activity_data: nil, verify_plus: nil,
97
98
  domain_info: nil, greylist_processing: nil, callback_url: nil, use_post: false)
98
- unless timeout.nil?
99
- timeout_i = Integer(timeout)
100
- if timeout_i < 3 || timeout_i > 60
101
- raise ArgumentError, 'Invalid parameter: timeout (must be between 3 and 60 seconds)'
102
- end
103
- end
99
+ __require_text__(email, 'email')
100
+ ip_address = __omit_blank__(ip_address, 'ip_address')
101
+ __whole_seconds__(timeout, 'timeout', 3, 60) unless timeout.nil?
104
102
  activity_data = __strict_bool__(activity_data, 'activity_data') unless activity_data.nil?
105
103
  verify_plus = __strict_bool__(verify_plus, 'verify_plus') unless verify_plus.nil?
106
104
  domain_info = __strict_bool__(domain_info, 'domain_info') unless domain_info.nil?
107
105
  greylist_processing = __strict_bool__(greylist_processing, 'greylist_processing') unless greylist_processing.nil?
108
106
  unless callback_url.nil?
109
- raise ArgumentError, 'Empty parameter: callback_url' if callback_url.to_s.strip.empty?
107
+ __require_text__(callback_url, 'callback_url')
110
108
 
111
109
  # The callback is where the greylist retry posts its result, so it is
112
110
  # meaningless - and rejected by the API - without the retry itself.
@@ -114,7 +112,10 @@ module Zerobounce
114
112
  raise ArgumentError, 'callback_url requires greylist_processing to be true'
115
113
  end
116
114
  end
117
- params = {email: email, ip_address: ip_address}
115
+ params = {email: email}
116
+ # Sent only when given, as in the other SDKs: a nil value went out as a
117
+ # bare "ip_address" parameter.
118
+ params[:ip_address] = ip_address unless ip_address.nil?
118
119
  params[:timeout] = timeout unless timeout.nil?
119
120
  unless activity_data.nil?
120
121
  params[:activity_data] = activity_data ? 'true' : 'false'
@@ -129,11 +130,12 @@ module Zerobounce
129
130
  params[:greylist_processing] = greylist_processing ? 'true' : 'false'
130
131
  end
131
132
  params[:callback_url] = callback_url unless callback_url.nil?
132
- if use_post
133
- @@request.post('validate', params, 'application/x-www-form-urlencoded')
134
- else
135
- @@request.get('validate', params)
136
- end
133
+ result = if use_post
134
+ @@request.post('validate', params, 'application/x-www-form-urlencoded')
135
+ else
136
+ @@request.get('validate', params)
137
+ end
138
+ result
137
139
  end
138
140
 
139
141
  # Get the number of remaining credits on the account.
@@ -142,8 +144,15 @@ module Zerobounce
142
144
  def credits()
143
145
  json = @@request.get('getcredits', {})
144
146
  credits = json['Credits']
145
- credits_i = credits.to_i
146
- return credits_i
147
+ return credits.to_i if credits.is_a?(String) && credits.match?(/\A-?[0-9]+\z/)
148
+ # zerobounce.net's example sends a JSON integer: {"Credits":2375323}.
149
+ return credits if credits.is_a?(Integer)
150
+
151
+ # E7: Credits is an integer, sent as a JSON string ("-1", "12345") or a
152
+ # JSON integer. A missing or null Credits, "abc", "5.0", 5.5 or true is
153
+ # the wrong shape for this call, not 0 credits (and not the NoMethodError
154
+ # [1].to_i raises).
155
+ raise ApiResponseError.new('ZeroBounce returned JSON of an unexpected shape: Credits is not an integer.', 200)
147
156
  end
148
157
 
149
158
  # Convenience method for checking if an email address is valid.
@@ -210,12 +219,17 @@ module Zerobounce
210
219
  # "end_date": "12/12/2023"
211
220
  # }
212
221
  def api_usage(start_date, end_date)
213
- begin
214
- start_date_f = start_date.strftime('%Y-%m-%d')
215
- end_date_f = end_date.strftime('%Y-%m-%d')
216
- rescue NoMethodError => e
217
- raise ArgumentError.new('strftime method not found for provided arguments')
222
+ [['start_date', start_date], ['end_date', end_date]].each do |name, value|
223
+ raise ArgumentError, "Empty parameter: #{name}" if value.nil?
224
+ unless value.is_a?(Date) || value.is_a?(Time)
225
+ raise ArgumentError, "Invalid parameter: #{name} must be a date"
226
+ end
218
227
  end
228
+ if start_date.to_date > end_date.to_date
229
+ raise ArgumentError, 'Invalid parameter: start_date must not be after end_date'
230
+ end
231
+ start_date_f = start_date.strftime('%Y-%m-%d')
232
+ end_date_f = end_date.strftime('%Y-%m-%d')
219
233
  params = {start_date: start_date_f, end_date: end_date_f}
220
234
  @@request.get('getapiusage', params)
221
235
  end
@@ -230,6 +244,7 @@ module Zerobounce
230
244
  # "active_in_days": "180"
231
245
  # }
232
246
  def activity(email)
247
+ __require_text__(email, 'email')
233
248
  params = {email: email}
234
249
  @@request.get('activity', params)
235
250
  end
@@ -241,6 +256,7 @@ module Zerobounce
241
256
  #
242
257
  # @return [Hash] e.g. {"email"=>"mark@gmail.com", "score"=>10}
243
258
  def score_email(email, use_post: false)
259
+ __require_text__(email, 'email')
244
260
  params = { email: email }
245
261
  if use_post
246
262
  @@request.post('scoring', params, 'application/x-www-form-urlencoded')
@@ -291,24 +307,20 @@ module Zerobounce
291
307
  # "errors": []
292
308
  # }
293
309
  def validate_batch(emails, ip_addresses=[], timeout: nil, activity_data: nil, verify_plus: nil)
294
- unless timeout.nil?
295
- timeout_i = Integer(timeout)
296
- if timeout_i < 10 || timeout_i > 120
297
- raise ArgumentError, 'Invalid parameter: timeout (must be between 10 and 120 seconds)'
298
- end
299
- end
310
+ __whole_seconds__(timeout, 'timeout', 10, 120) unless timeout.nil?
300
311
 
301
- raise ArgumentError.new if emails.class != Array
302
- emails.each do |email|
303
- raise ArgumentError if email.class != String
304
- end
312
+ raise ArgumentError, 'Invalid parameter: emails must be an Array of Strings' unless emails.is_a?(Array)
313
+ raise ArgumentError, 'Empty parameter: emails' if emails.empty?
305
314
 
306
- email_batch = []
307
- emails.each_index do |i|
308
- email_batch.push({
309
- email_address: emails[i],
310
- ip_address: ip_addresses[i]
311
- })
315
+ ip_addresses = [] if ip_addresses.nil?
316
+ raise ArgumentError, 'Invalid parameter: ip_addresses must be an Array of Strings' unless ip_addresses.is_a?(Array)
317
+
318
+ email_batch = emails.each_with_index.map do |email, i|
319
+ entry = { email_address: __require_text__(email, 'emails') }
320
+ # Omitted, not sent as null, when no IP was given for the address.
321
+ ip = __omit_blank__(ip_addresses[i], 'ip_addresses')
322
+ entry[:ip_address] = ip unless ip.nil?
323
+ entry
312
324
  end
313
325
  params = {email_batch: email_batch}
314
326
  # LIVE: validatebatch takes timeout as a JSON *string*. Sent as a number
@@ -317,8 +329,7 @@ module Zerobounce
317
329
  params[:timeout] = timeout.to_s unless timeout.nil?
318
330
  params[:activity_data] = __strict_bool__(activity_data, 'activity_data') unless activity_data.nil?
319
331
  params[:verify_plus] = __strict_bool__(verify_plus, 'verify_plus') unless verify_plus.nil?
320
- results = @@request.post('validatebatch', params)
321
- results
332
+ @@request.post('validatebatch', params)
322
333
  end
323
334
 
324
335
  # Validate CSV file
@@ -328,8 +339,13 @@ module Zerobounce
328
339
  # @option [Int] :first_name_column Specify which column the first name is on
329
340
  # @option [Int] :last_name_column Specify which column the last name is on
330
341
  # @option [Int] :gender_column Specify which column the gender is on
331
- # @option [Int] :has_header_row Specify whether the file includes a header row or not
332
- # @option [Int] :return_url Specify a callback URL (if nil, no callback will be performed)
342
+ # @option [Int] :ip_address_column Specify which column the signup IP address is on
343
+ # @option [Boolean] :has_header_row Whether the file includes a header row; sent only when given
344
+ # @option [Boolean] :remove_duplicate Whether the API removes duplicate emails (the API's default is true)
345
+ # @option [String] :return_url Specify a callback URL (if nil, no callback will be performed)
346
+ #
347
+ # The column options, +remove_duplicate+ and +allow_phase_2+ are sent only
348
+ # when given.
333
349
  #
334
350
  # @return [Hash]
335
351
  # {
@@ -341,19 +357,24 @@ module Zerobounce
341
357
  def validate_file_send(
342
358
  filepath,
343
359
  email_address_column: 1,
344
- first_name_column: 2,
345
- last_name_column: 3,
346
- gender_column: 4,
347
- has_header_row: true,
360
+ first_name_column: nil,
361
+ last_name_column: nil,
362
+ gender_column: nil,
363
+ ip_address_column: nil,
364
+ has_header_row: nil,
365
+ remove_duplicate: nil,
348
366
  return_url: nil,
349
367
  allow_phase_2: nil
350
368
  )
351
- params = { email_address_column: email_address_column }
369
+ params = { email_address_column: __column__(email_address_column, 'email_address_column') }
352
370
  params[:has_header_row] = __wire_bool__(has_header_row, 'has_header_row') unless has_header_row.nil?
353
- params[:first_name_column] = first_name_column unless first_name_column.nil?
354
- params[:last_name_column] = last_name_column unless last_name_column.nil?
355
- params[:gender_column] = gender_column unless gender_column.nil?
356
- params[:return_url] = return_url unless return_url.nil? || return_url.to_s.empty?
371
+ params[:first_name_column] = __column__(first_name_column, 'first_name_column') unless first_name_column.nil?
372
+ params[:last_name_column] = __column__(last_name_column, 'last_name_column') unless last_name_column.nil?
373
+ params[:gender_column] = __column__(gender_column, 'gender_column') unless gender_column.nil?
374
+ params[:ip_address_column] = __column__(ip_address_column, 'ip_address_column') unless ip_address_column.nil?
375
+ params[:remove_duplicate] = __wire_bool__(remove_duplicate, 'remove_duplicate') unless remove_duplicate.nil?
376
+ return_url = __omit_blank__(return_url, 'return_url')
377
+ params[:return_url] = return_url unless return_url.nil?
357
378
  unless allow_phase_2.nil?
358
379
  params[:allow_phase_2] = __wire_bool__(allow_phase_2, 'allow_phase_2')
359
380
  end
@@ -368,18 +389,17 @@ module Zerobounce
368
389
  # @option [Int] :first_name_column
369
390
  # @option [Int] :last_name_column
370
391
  # @option [Int] :gender_column
371
- # @option [Int] :has_header_row
372
- # @option [Int] :return_url
392
+ # @option [Int] :ip_address_column
393
+ # @option [Boolean] :has_header_row
394
+ # @option [Boolean] :remove_duplicate
395
+ # @option [String] :return_url
373
396
  # @option [Boolean] :allow_phase_2 When set, sends allow_phase_2 (validation bulk only).
374
397
  # @return [Hash] same as validate_file_send
375
398
  def validate_file_send_stream(io, file_name, **opts)
376
- content = io.respond_to?(:read) ? io.read : io.to_s
377
- Tempfile.create(['zb', File.extname(file_name)]) do |tmp|
378
- tmp.binmode
379
- tmp.write(content)
380
- tmp.rewind
381
- validate_file_send(tmp.path, **opts)
382
- end
399
+ content = __stream_content__(io, file_name)
400
+ # Uploaded from memory: a Tempfile in Dir.tmpdir failed the check that
401
+ # keeps file paths under the current directory (2.0.1 to 3.0.1).
402
+ validate_file_send(BaseRequest::Upload.new(content, file_name), **opts)
383
403
  end
384
404
 
385
405
  # Get validate file status
@@ -398,7 +418,7 @@ module Zerobounce
398
418
  # "return_url": null
399
419
  # }
400
420
  def validate_file_check(file_id)
401
- # todo:
421
+ __require_text__(file_id, 'file_id')
402
422
  params = {file_id: file_id}
403
423
  @@request.bulk_get('filestatus', params)
404
424
  end
@@ -411,6 +431,7 @@ module Zerobounce
411
431
  # @return [String] file body on success
412
432
  # @raise [RuntimeError] on API/JSON error responses
413
433
  def validate_file_get(file_id, options = nil)
434
+ __require_text__(file_id, 'file_id')
414
435
  params = { file_id: file_id }
415
436
  if options
416
437
  params[:download_type] = options.download_type if options.download_type
@@ -433,7 +454,7 @@ module Zerobounce
433
454
  # "file_id": "6d44a908-7283-42a9-aa5f-9e57b16f84bd"
434
455
  # }
435
456
  def validate_file_delete(file_id)
436
- # todo:
457
+ __require_text__(file_id, 'file_id')
437
458
  params = {file_id: file_id}
438
459
  @@request.bulk_get('deletefile', params)
439
460
  end
@@ -442,8 +463,9 @@ module Zerobounce
442
463
  #
443
464
  # @param [String] :filepath Path to the file to be uploaded
444
465
  # @option [Int] :email_address_column Specify which column the email address is on
445
- # @option [Int] :has_header_row Specify whether the file includes a header row or not
446
- # @option [Int] :return_url Specify a callback URL (if nil, no callback will be performed)
466
+ # @option [Boolean] :has_header_row Whether the file includes a header row (default false)
467
+ # @option [Boolean] :remove_duplicate Whether the API removes duplicate emails; sent only when given
468
+ # @option [String] :return_url Specify a callback URL (if nil, no callback will be performed)
447
469
  #
448
470
  # @return [Hash]
449
471
  # {
@@ -455,12 +477,15 @@ module Zerobounce
455
477
  def scoring_file_send(
456
478
  filepath,
457
479
  email_address_column: 1,
458
- has_header_row: true,
480
+ has_header_row: false,
481
+ remove_duplicate: nil,
459
482
  return_url: nil
460
483
  )
461
- params = { email_address_column: email_address_column }
484
+ params = { email_address_column: __column__(email_address_column, 'email_address_column') }
462
485
  params[:has_header_row] = __wire_bool__(has_header_row, 'has_header_row') unless has_header_row.nil?
463
- params[:return_url] = return_url if return_url
486
+ params[:remove_duplicate] = __wire_bool__(remove_duplicate, 'remove_duplicate') unless remove_duplicate.nil?
487
+ return_url = __omit_blank__(return_url, 'return_url')
488
+ params[:return_url] = return_url unless return_url.nil?
464
489
  @@request.bulk_post('scoring/sendfile', params, 'multipart/form-data', filepath)
465
490
  end
466
491
 
@@ -469,17 +494,15 @@ module Zerobounce
469
494
  # @param [IO, String] io Stream or string content to upload
470
495
  # @param [String] file_name Filename for the upload (e.g. "emails.csv")
471
496
  # @option [Int] :email_address_column (same as scoring_file_send)
472
- # @option [Int] :has_header_row
473
- # @option [Int] :return_url
497
+ # @option [Boolean] :has_header_row
498
+ # @option [Boolean] :remove_duplicate
499
+ # @option [String] :return_url
474
500
  # @return [Hash] same as scoring_file_send
475
501
  def scoring_file_send_stream(io, file_name, **opts)
476
- content = io.respond_to?(:read) ? io.read : io.to_s
477
- Tempfile.create(['zb', File.extname(file_name)]) do |tmp|
478
- tmp.binmode
479
- tmp.write(content)
480
- tmp.rewind
481
- scoring_file_send(tmp.path, **opts)
482
- end
502
+ content = __stream_content__(io, file_name)
503
+ # Uploaded from memory: a Tempfile in Dir.tmpdir failed the check that
504
+ # keeps file paths under the current directory (2.0.1 to 3.0.1).
505
+ scoring_file_send(BaseRequest::Upload.new(content, file_name), **opts)
483
506
  end
484
507
 
485
508
  # Get scoring bulk results file
@@ -490,6 +513,7 @@ module Zerobounce
490
513
  # @return [String] file body on success
491
514
  # @raise [RuntimeError] on API/JSON error responses
492
515
  def scoring_file_get(file_id, options = nil)
516
+ __require_text__(file_id, 'file_id')
493
517
  params = { file_id: file_id }
494
518
  if options && options.download_type
495
519
  params[:download_type] = options.download_type
@@ -512,6 +536,7 @@ module Zerobounce
512
536
  # "return_url": null
513
537
  # }
514
538
  def scoring_file_check(file_id)
539
+ __require_text__(file_id, 'file_id')
515
540
  params = {file_id: file_id}
516
541
  @@request.bulk_get('scoring/filestatus', params)
517
542
  end
@@ -528,6 +553,7 @@ module Zerobounce
528
553
  # "file_id": "6d44a908-7283-42a9-aa5f-9e57b16f84bd"
529
554
  # }
530
555
  def scoring_file_delete(file_id)
556
+ __require_text__(file_id, 'file_id')
531
557
  params = {file_id: file_id}
532
558
  @@request.bulk_get('scoring/deletefile', params)
533
559
  end
@@ -582,10 +608,11 @@ module Zerobounce
582
608
  def guessformat(domain, first_name: '', middle_name: '', last_name: '')
583
609
  warn "[DEPRECATION] `guessformat` is deprecated and will be removed in a future version.\n" \
584
610
  "Please use `find_email` or `find_domain` instead."
585
- params = {domain: domain}
586
- params[:first_name] = first_name unless first_name.nil? || first_name.empty?
587
- params[:middle_name] = middle_name unless middle_name.nil? || middle_name.empty?
588
- params[:last_name] = last_name unless last_name.nil? || last_name.empty?
611
+ params = { domain: __require_text__(domain, 'domain') }
612
+ { first_name: first_name, middle_name: middle_name, last_name: last_name }.each do |key, value|
613
+ value = __omit_blank__(value, key.to_s)
614
+ params[key] = value unless value.nil?
615
+ end
589
616
  @@request.get('guessformat', params)
590
617
  end
591
618
 
@@ -612,19 +639,14 @@ module Zerobounce
612
639
  # name, and answers the domain's format when no name is given. It stays the
613
640
  # first positional argument, so every existing call keeps working.
614
641
  def find_email(first_name = nil, domain: '', company_name: '', middle_name: '', last_name: '')
615
- # Validate that exactly one of domain or company_name is provided
616
- if (domain.nil? || domain.empty?) && (company_name.nil? || company_name.empty?)
617
- raise ArgumentError, "Either domain or company_name must be provided"
618
- elsif !(domain.nil? || domain.empty?) && !(company_name.nil? || company_name.empty?)
619
- raise ArgumentError, "Only one of domain or company_name can be provided"
620
- end
642
+ domain, company_name = __domain_or_company__(domain, company_name)
621
643
 
622
644
  params = {}
623
- params[:first_name] = first_name unless first_name.nil? || first_name.to_s.empty?
624
- params[:domain] = domain unless domain.nil? || domain.empty?
625
- params[:company_name] = company_name unless company_name.nil? || company_name.empty?
626
- params[:middle_name] = middle_name unless middle_name.nil? || middle_name.empty?
627
- params[:last_name] = last_name unless last_name.nil? || last_name.empty?
645
+ { first_name: first_name }.merge(domain: domain, company_name: company_name,
646
+ middle_name: middle_name, last_name: last_name).each do |key, value|
647
+ value = __omit_blank__(value, key.to_s)
648
+ params[key] = value unless value.nil?
649
+ end
628
650
 
629
651
  @@request.get('guessformat', params)
630
652
  end
@@ -688,19 +710,38 @@ module Zerobounce
688
710
  # ]
689
711
  # }
690
712
  def find_domain(domain: '', company_name: '')
691
- # Validate that exactly one of domain or company_name is provided
692
- if (domain.nil? || domain.empty?) && (company_name.nil? || company_name.empty?)
693
- raise ArgumentError, "Either domain or company_name must be provided"
694
- elsif !(domain.nil? || domain.empty?) && !(company_name.nil? || company_name.empty?)
695
- raise ArgumentError, "Only one of domain or company_name can be provided"
696
- end
713
+ domain, company_name = __domain_or_company__(domain, company_name)
697
714
 
698
715
  params = {}
699
- params[:domain] = domain unless domain.nil? || domain.empty?
700
- params[:company_name] = company_name unless company_name.nil? || company_name.empty?
716
+ params[:domain] = domain unless domain.nil?
717
+ params[:company_name] = company_name unless company_name.nil?
701
718
 
702
719
  @@request.get('guessformat', params)
703
720
  end
704
721
 
722
+ private
723
+
724
+ # Exactly one of domain and company_name, each a non-blank String; the
725
+ # blank one comes back nil.
726
+ def __domain_or_company__(domain, company_name)
727
+ domain = __omit_blank__(domain, 'domain')
728
+ company_name = __omit_blank__(company_name, 'company_name')
729
+ raise ArgumentError, 'Either domain or company_name must be provided' if domain.nil? && company_name.nil?
730
+ raise ArgumentError, 'Only one of domain or company_name can be provided' if domain && company_name
731
+
732
+ [domain, company_name]
733
+ end
734
+
735
+ # The content of a stream upload: a readable, non-empty one with a name.
736
+ def __stream_content__(io, file_name)
737
+ raise ArgumentError, 'Empty parameter: io' if io.nil?
738
+
739
+ __require_text__(file_name, 'file_name')
740
+ content = BaseRequest.read_stream(io)
741
+ raise ArgumentError, 'Empty parameter: io' if content.empty?
742
+
743
+ content
744
+ end
745
+
705
746
  end
706
747
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: zerobounce-sdk
3
3
  version: !ruby/object:Gem::Version
4
- version: 3.0.0
4
+ version: 3.1.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Zero Bounce
@@ -9,20 +9,6 @@ bindir: exe
9
9
  cert_chain: []
10
10
  date: 1980-01-02 00:00:00.000000000 Z
11
11
  dependencies:
12
- - !ruby/object:Gem::Dependency
13
- name: rest-client
14
- requirement: !ruby/object:Gem::Requirement
15
- requirements:
16
- - - "~>"
17
- - !ruby/object:Gem::Version
18
- version: '2.1'
19
- type: :runtime
20
- prerelease: false
21
- version_requirements: !ruby/object:Gem::Requirement
22
- requirements:
23
- - - "~>"
24
- - !ruby/object:Gem::Version
25
- version: '2.1'
26
12
  - !ruby/object:Gem::Dependency
27
13
  name: dotenv
28
14
  requirement: !ruby/object:Gem::Requirement
@@ -331,9 +317,13 @@ files:
331
317
  - lib/zerobounce/error.rb
332
318
  - lib/zerobounce/get_file_helper.rb
333
319
  - lib/zerobounce/get_file_options.rb
320
+ - lib/zerobounce/http_transport.rb
334
321
  - lib/zerobounce/priority3.rb
335
322
  - lib/zerobounce/request.rb
336
323
  - lib/zerobounce/response_error.rb
324
+ - lib/zerobounce/response_shape.rb
325
+ - lib/zerobounce/strict_bool.rb
326
+ - lib/zerobounce/strict_json.rb
337
327
  - lib/zerobounce/validate_status.rb
338
328
  - lib/zerobounce/validate_sub_status.rb
339
329
  - lib/zerobounce/version.rb