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.
@@ -0,0 +1,229 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'net/http'
4
+ require 'uri'
5
+ require 'cgi'
6
+ require 'openssl'
7
+ require 'securerandom'
8
+ require 'stringio'
9
+ require 'zlib'
10
+ require 'zerobounce/error'
11
+
12
+ # rubocop:disable Metrics/ModuleLength, Metrics/ParameterLists, Metrics/AbcSize, Metrics/MethodLength
13
+ # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
14
+ module Zerobounce
15
+ # The SDK's HTTP layer, on Ruby's built-in Net::HTTP (no runtime dependency).
16
+ #
17
+ # One request, one response: no redirects are followed, nothing is logged
18
+ # (Net::HTTP's debug output is never switched on), and every transport
19
+ # failure (refused, reset, timeout, TLS, a body cut short) raises
20
+ # {ApiResponseError} with status 0 and a redacted message. An HTTP error
21
+ # status is NOT raised here: the response comes back and the caller turns it
22
+ # into an error.
23
+ module HttpTransport
24
+ OPEN_TIMEOUT = 30
25
+ READ_TIMEOUT = 120
26
+ WRITE_TIMEOUT = 120
27
+
28
+ # Response headers, readable as headers[:content_type] or
29
+ # headers['Content-Type'] (any case).
30
+ class Headers < Hash
31
+ def self.normalize(key)
32
+ key.to_s.downcase.tr('-', '_').to_sym
33
+ end
34
+
35
+ def [](key)
36
+ super(self.class.normalize(key))
37
+ end
38
+
39
+ def key?(key)
40
+ super(self.class.normalize(key))
41
+ end
42
+ end
43
+
44
+ # The parts of a response the SDK reads: #code (Integer), #body (String),
45
+ # #headers.
46
+ class Response
47
+ attr_reader :code, :body, :headers
48
+
49
+ def initialize(code, body, headers)
50
+ @code = code
51
+ @body = body
52
+ @headers = headers
53
+ end
54
+
55
+ def to_s
56
+ @body
57
+ end
58
+ end
59
+
60
+ module_function
61
+
62
+ # @param redact [#call] turns an error text into its redacted form
63
+ def execute(method:, url:, query: nil, headers: {}, body: nil, redact: nil)
64
+ redact ||= ->(text) { text }
65
+ uri = build_uri(url, query)
66
+ request = build_request(method, uri, headers, body)
67
+ perform(uri, request, redact)
68
+ rescue ApiResponseError
69
+ raise
70
+ rescue StandardError => e
71
+ raise failure(e, redact), cause: nil
72
+ end
73
+
74
+ def failure(error, redact)
75
+ ApiResponseError.new(
76
+ redact.call("The request to ZeroBounce failed (#{error.class}): #{error.message}"), 0
77
+ )
78
+ end
79
+
80
+ def build_uri(url, query)
81
+ encoded = encode_query(query)
82
+ full = url.to_s
83
+ full += (full.include?('?') ? '&' : '?') + encoded unless encoded.empty?
84
+ URI.parse(full)
85
+ end
86
+
87
+ def build_request(method, uri, headers, body)
88
+ klass = Net::HTTP.const_get(method.to_s.capitalize)
89
+ request = klass.new(uri.request_uri)
90
+ # Identity: Net::HTTP would otherwise ask for gzip, decompress it and
91
+ # drop Content-Length, so a body cut short could no longer be told from a
92
+ # complete one.
93
+ request['Accept-Encoding'] = 'identity'
94
+ request['Accept'] = '*/*'
95
+ headers.each { |name, value| request[name.to_s.tr('_', '-')] = value.to_s unless value.nil? }
96
+ request.body = body unless body.nil?
97
+ request
98
+ end
99
+
100
+ def perform(uri, request, redact)
101
+ http = Net::HTTP.new(uri.host, uri.port)
102
+ http.use_ssl = uri.scheme == 'https'
103
+ http.open_timeout = OPEN_TIMEOUT
104
+ http.read_timeout = READ_TIMEOUT
105
+ http.write_timeout = WRITE_TIMEOUT
106
+ # No silent second send: Net::HTTP would otherwise re-send an idempotent
107
+ # request (GET, PUT, DELETE) once after an EOF or reset, and a validation
108
+ # GET is billable.
109
+ http.max_retries = 0
110
+ http.start do
111
+ http.request(request) { |res| return wrap(res, redact) }
112
+ end
113
+ end
114
+
115
+ def wrap(res, redact)
116
+ headers = Headers.new
117
+ res.each_header { |name, value| headers[Headers.normalize(name)] = value }
118
+ raw = res.read_body.to_s.b
119
+ check_length!(res, raw, redact)
120
+ body = decode(res, raw, redact)
121
+ Response.new(res.code.to_i, with_charset(body, res['content-type']), headers)
122
+ end
123
+
124
+ # Fewer bytes than Content-Length is a failure, status 0 (a connection
125
+ # that closes mid-body must not read as a complete response). A list-form
126
+ # header ("50, 50") counts as its value when every entry agrees; entries
127
+ # that differ are a failure too.
128
+ def check_length!(res, raw, redact)
129
+ return if [204, 304].include?(res.code.to_i)
130
+
131
+ lengths = res['content-length'].to_s.split(',').map(&:strip)
132
+ return if lengths.empty? || lengths.any? { |length| !length.match?(/\A\d+\z/) }
133
+
134
+ if lengths.uniq.size > 1
135
+ raise ApiResponseError.new(
136
+ redact.call("The response from ZeroBounce had conflicting Content-Length values (#{lengths.join(', ')})."), 0
137
+ )
138
+ end
139
+ return unless raw.bytesize < lengths.first.to_i
140
+
141
+ raise ApiResponseError.new(
142
+ redact.call("The response from ZeroBounce was cut short: #{raw.bytesize} of #{lengths.first} " \
143
+ 'bytes arrived before the connection closed.'), 0
144
+ )
145
+ end
146
+
147
+ # Identity is requested, so a compressed body is unexpected; if a server
148
+ # sends one anyway it must be a complete stream (a gzip body without its
149
+ # trailer is a body cut short).
150
+ def decode(res, raw, redact)
151
+ case res['content-encoding'].to_s.downcase
152
+ when 'gzip', 'x-gzip'
153
+ gunzip(raw)
154
+ when 'deflate'
155
+ Zlib::Inflate.inflate(raw)
156
+ else
157
+ raw
158
+ end
159
+ rescue Zlib::Error
160
+ # cause: nil, so the Zlib error (whose message can quote the raw body)
161
+ # is not carried along.
162
+ raise ApiResponseError.new(redact.call('The response from ZeroBounce could not be decoded.'), 0), cause: nil
163
+ end
164
+
165
+ def gunzip(raw)
166
+ reader = Zlib::GzipReader.new(StringIO.new(raw))
167
+ text = reader.read.to_s
168
+ reader.finish # raises Zlib::GzipFile::Error unless the stream (with its trailer) was complete
169
+ text
170
+ end
171
+
172
+ def with_charset(body, content_type)
173
+ charset = content_type.to_s[/charset=["']?([\w.:-]+)/i, 1]
174
+ encoding = begin
175
+ charset ? Encoding.find(charset) : Encoding::UTF_8
176
+ rescue ArgumentError
177
+ Encoding::UTF_8
178
+ end
179
+ body.dup.force_encoding(encoding)
180
+ end
181
+
182
+ # key=value pairs, nested hashes as k[sub] and arrays as k[].
183
+ def flatten_params(params, parent = nil)
184
+ return [] if params.nil?
185
+
186
+ params.flat_map do |key, value|
187
+ name = parent ? "#{parent}[#{key}]" : key.to_s
188
+ if value.is_a?(Hash)
189
+ flatten_params(value, name)
190
+ elsif value.is_a?(Array)
191
+ value.flat_map { |item| item.is_a?(Hash) ? flatten_params(item, "#{name}[]") : [["#{name}[]", item]] }
192
+ else
193
+ [[name, value]]
194
+ end
195
+ end
196
+ end
197
+
198
+ def encode_query(params)
199
+ flatten_params(params).map do |key, value|
200
+ value.nil? ? CGI.escape(key) : "#{CGI.escape(key)}=#{CGI.escape(value.to_s)}"
201
+ end.join('&')
202
+ end
203
+
204
+ # A multipart/form-data body, built here. Returns [content_type, body].
205
+ # +file+ is { name:, filename:, content:, content_type: }.
206
+ def multipart(fields, file)
207
+ boundary = "----ZerobounceRubyBoundary#{SecureRandom.hex(16)}"
208
+ body = String.new(encoding: Encoding::BINARY)
209
+ flatten_params(fields).each do |name, value|
210
+ body << "--#{boundary}\r\n".b
211
+ body << "Content-Disposition: form-data; name=\"#{quote(name)}\"\r\n\r\n".b
212
+ body << value.to_s.b << "\r\n".b
213
+ end
214
+ body << "--#{boundary}\r\n".b
215
+ body << "Content-Disposition: form-data; name=\"#{quote(file[:name])}\"; " \
216
+ "filename=\"#{quote(file[:filename])}\"\r\n".b
217
+ body << "Content-Type: #{file[:content_type]}\r\n\r\n".b
218
+ body << file[:content].to_s.b << "\r\n--#{boundary}--\r\n".b
219
+ ["multipart/form-data; boundary=#{boundary}", body]
220
+ end
221
+
222
+ # A header parameter value: raw UTF-8, a quote as %22, CR and LF removed.
223
+ def quote(text)
224
+ text.to_s.delete("\r\n").gsub('"', '%22')
225
+ end
226
+ end
227
+ end
228
+ # rubocop:enable Metrics/ModuleLength, Metrics/ParameterLists, Metrics/AbcSize, Metrics/MethodLength
229
+ # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
@@ -1,6 +1,10 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require 'date'
3
4
  require 'erb'
5
+ require 'uri'
6
+ require 'zerobounce/strict_bool'
7
+ require 'zerobounce/response_shape'
4
8
 
5
9
  module Zerobounce
6
10
  module Priority3
@@ -13,65 +17,85 @@ module Zerobounce
13
17
  INBOX_PLACEMENT_PAGE_SIZE_MIN = 1
14
18
  INBOX_PLACEMENT_PAGE_SIZE_MAX = 100
15
19
 
20
+ INBOX_PLACEMENT_STATUSES = %w[running finished].freeze
21
+ IPT_CREATE_OPTIONS = %i[test_type sender_email provider_ids seed_ids providers webhook_url].freeze
22
+ IPT_LIST_OPTIONS = %i[status created_after created_before page page_size].freeze
23
+ FILE_JOB_OPTIONS = %i[return_url remove_duplicates].freeze
24
+ # The custom filters' documented values (as the Python SDK checks them).
25
+ FILTER_RULES = %w[allow block].freeze
26
+ FILTER_TARGETS = %w[email domain mx tld].freeze
27
+
16
28
  def zb_request
17
29
  Zerobounce.class_variable_get(:@@request)
18
30
  end
19
31
 
20
32
  def send_email_finder_file(filepath, domain_column:, first_name_column: nil, last_name_column: nil,
21
33
  middle_name_column: nil, full_name_column: nil, has_header_row: nil)
22
- raise ArgumentError, 'domain_column is required' if domain_column.nil? || domain_column.to_i < 1
34
+ params = { domain_column: __column__(domain_column, 'domain_column') }
35
+ {
36
+ first_name_column: first_name_column, last_name_column: last_name_column,
37
+ middle_name_column: middle_name_column, full_name_column: full_name_column
38
+ }.each do |name, value|
39
+ # A blank name column is "not given", so the one-of check below speaks.
40
+ next if value.nil? || (value.is_a?(String) && value.strip.empty?)
41
+
42
+ params[name] = __column__(value, name.to_s)
43
+ end
23
44
  # One of the two name columns tells the finder what to look for; with
24
45
  # neither there is nothing to build a local part from.
25
- if __blank__(first_name_column) && __blank__(full_name_column)
46
+ if params[:first_name_column].nil? && params[:full_name_column].nil?
26
47
  raise ArgumentError, 'first_name_column or full_name_column is required'
27
48
  end
28
49
 
29
- params = { domain_column: domain_column }
30
50
  params[:has_header_row] = __wire_bool__(has_header_row, 'has_header_row') unless has_header_row.nil?
31
- params[:first_name_column] = first_name_column unless first_name_column.nil?
32
- params[:last_name_column] = last_name_column unless last_name_column.nil?
33
- params[:middle_name_column] = middle_name_column unless middle_name_column.nil?
34
- params[:full_name_column] = full_name_column unless full_name_column.nil?
35
51
  zb_request.bulk_root_post("#{EMAIL_FINDER_BULK_BASE}/sendfile", params, 'multipart/form-data', filepath)
36
52
  end
37
53
 
38
54
  def email_finder_file_status(file_id)
55
+ __require_text__(file_id, 'file_id')
39
56
  zb_request.bulk_root_get("#{EMAIL_FINDER_BULK_BASE}/filestatus", { file_id: file_id })
40
57
  end
41
58
 
42
59
  def email_finder_file_get(file_id)
60
+ __require_text__(file_id, 'file_id')
43
61
  zb_request.bulk_root_getfile("#{EMAIL_FINDER_BULK_BASE}/getfile", { file_id: file_id })
44
62
  end
45
63
 
46
64
  def email_finder_file_delete(file_id)
65
+ __require_text__(file_id, 'file_id')
47
66
  zb_request.bulk_root_get("#{EMAIL_FINDER_BULK_BASE}/deletefile", { file_id: file_id })
48
67
  end
49
68
 
50
69
  def send_domain_search_file(filepath, domain_column:, has_header_row: nil)
51
- raise ArgumentError, 'domain_column is required' if domain_column.nil? || domain_column.to_i < 1
52
-
53
- params = { domain_column: domain_column }
70
+ params = { domain_column: __column__(domain_column, 'domain_column') }
54
71
  params[:has_header_row] = __wire_bool__(has_header_row, 'has_header_row') unless has_header_row.nil?
55
72
  zb_request.bulk_root_post("#{DOMAIN_SEARCH_BULK_BASE}/sendfile", params, 'multipart/form-data', filepath)
56
73
  end
57
74
 
58
75
  def domain_search_file_status(file_id)
76
+ __require_text__(file_id, 'file_id')
59
77
  zb_request.bulk_root_get("#{DOMAIN_SEARCH_BULK_BASE}/filestatus", { file_id: file_id })
60
78
  end
61
79
 
62
80
  def domain_search_file_get(file_id)
81
+ __require_text__(file_id, 'file_id')
63
82
  zb_request.bulk_root_getfile("#{DOMAIN_SEARCH_BULK_BASE}/getfile", { file_id: file_id })
64
83
  end
65
84
 
66
85
  def domain_search_file_delete(file_id)
86
+ __require_text__(file_id, 'file_id')
67
87
  zb_request.bulk_root_get("#{DOMAIN_SEARCH_BULK_BASE}/deletefile", { file_id: file_id })
68
88
  end
69
89
 
70
90
  def send_list_evaluator_file(filepath, email_address_column:)
71
- raise ArgumentError, 'email_address_column is required' if email_address_column.nil? || email_address_column.to_i < 1
72
-
73
- params = { email_address_column: email_address_column }
74
- zb_request.bulk_post('listevaluator/', params, 'multipart/form-data', filepath)
91
+ params = { email_address_column: __column__(email_address_column, 'email_address_column') }
92
+ # The same base URL as get_list_evaluator_result, not the bulk one. The
93
+ # endpoint is the base URL itself, with its trailing slash.
94
+ ResponseShape.check!(
95
+ zb_request.bulk_post('', params, 'multipart/form-data', filepath,
96
+ root: Zerobounce.configuration.list_evaluator_root_url),
97
+ :list_evaluator
98
+ )
75
99
  end
76
100
 
77
101
  def get_list_evaluator_result(file_id)
@@ -79,11 +103,14 @@ module Zerobounce
79
103
 
80
104
  # The list evaluator has its own base URL, not a path built from the bulk
81
105
  # one, and the file id is one path segment, so a slash must stay encoded.
82
- zb_request.root_request(
83
- :get,
84
- Zerobounce.configuration.list_evaluator_root_url,
85
- "#{ERB::Util.url_encode(file_id.to_s.strip)}/",
86
- {}
106
+ ResponseShape.check!(
107
+ zb_request.root_request(
108
+ :get,
109
+ Zerobounce.configuration.list_evaluator_root_url,
110
+ "#{ERB::Util.url_encode(file_id.to_s.strip)}/",
111
+ {}
112
+ ),
113
+ :list_evaluator
87
114
  )
88
115
  end
89
116
 
@@ -102,11 +129,12 @@ module Zerobounce
102
129
  end
103
130
 
104
131
  def add_filter(rule:, target:, value:)
132
+ __check_filter__(rule, target, value)
105
133
  zb_request.post('filters/add', { rule: rule, target: target, value: value }, 'application/x-www-form-urlencoded')
106
134
  end
107
135
 
108
136
  def list_filters(use_post: false)
109
- if use_post
137
+ if __strict_bool__(use_post, 'use_post')
110
138
  zb_request.post('filters/list', {}, 'application/x-www-form-urlencoded')
111
139
  else
112
140
  zb_request.get('filters/list', {})
@@ -114,13 +142,16 @@ module Zerobounce
114
142
  end
115
143
 
116
144
  def delete_filter(rule:, target:, value:)
145
+ __check_filter__(rule, target, value)
117
146
  zb_request.post('filters/delete', { rule: rule, target: target, value: value }, 'application/x-www-form-urlencoded')
118
147
  end
119
148
 
120
149
  def list_s3_files(bucket: nil, search: nil)
121
150
  params = {}
122
- params[:bucket] = bucket unless bucket.nil? || bucket.to_s.empty?
123
- params[:search] = search unless search.nil? || search.to_s.empty?
151
+ bucket = __omit_blank__(bucket, 'bucket')
152
+ search = __omit_blank__(search, 'search')
153
+ params[:bucket] = bucket unless bucket.nil?
154
+ params[:search] = search unless search.nil?
124
155
  # The S3 listing lives on the bulkapi ROOT, like the jobs below it, not
125
156
  # under /v2 - bulk_get would send it to /v2/listS3files, which is a 404.
126
157
  zb_request.bulk_root_get('listS3files', params)
@@ -139,12 +170,13 @@ module Zerobounce
139
170
  # export_bucket is optional: omit it and the export goes to the bucket in
140
171
  # your ZeroBounce settings, the way export_sftp_file's export_path does.
141
172
  def export_s3_file(file_id:, export_bucket: nil)
142
- raise ArgumentError, 'file_id is required' if file_id.nil? || file_id.to_s.strip.empty?
143
-
173
+ __require_text__(file_id, 'file_id')
144
174
  if !export_bucket.nil? && export_bucket.to_s.strip.empty?
145
175
  raise ArgumentError, 'export_bucket is required'
146
176
  end
147
177
 
178
+ __require_text__(export_bucket, 'export_bucket') unless export_bucket.nil?
179
+
148
180
  params = { file_id: file_id }
149
181
  params[:export_bucket] = export_bucket unless export_bucket.nil?
150
182
  zb_request.bulk_root_form_post('exportS3file', params)
@@ -187,12 +219,13 @@ module Zerobounce
187
219
  # Note the field name: this endpoint takes export_path, not the
188
220
  # export_bucket that export_s3_file sends. Omit it to use your settings.
189
221
  def export_sftp_file(file_id:, export_path: nil)
190
- raise ArgumentError, 'file_id is required' if file_id.nil? || file_id.to_s.strip.empty?
191
-
222
+ __require_text__(file_id, 'file_id')
192
223
  if !export_path.nil? && export_path.to_s.strip.empty?
193
224
  raise ArgumentError, 'export_path is required'
194
225
  end
195
226
 
227
+ __require_text__(export_path, 'export_path') unless export_path.nil?
228
+
196
229
  params = { file_id: file_id }
197
230
  params[:export_path] = export_path unless export_path.nil?
198
231
  zb_request.bulk_root_form_post('exportSFTPfile', params)
@@ -216,7 +249,10 @@ module Zerobounce
216
249
  # three are rejected by the API, so they are caught before a request that
217
250
  # would spend inbox-test credits.
218
251
  def create_inbox_placement_test(name, **options)
252
+ __check_options__(options, IPT_CREATE_OPTIONS)
219
253
  raise ArgumentError, 'name is required' if name.nil? || name.to_s.strip.empty?
254
+
255
+ __require_text__(name, 'name')
220
256
  raise ArgumentError, 'name must be 64 characters or fewer' if name.to_s.strip.length > INBOX_PLACEMENT_NAME_MAX
221
257
 
222
258
  if options.key?(:test_type)
@@ -225,6 +261,13 @@ module Zerobounce
225
261
  raise ArgumentError, 'sender_email is required when test_type is 1'
226
262
  end
227
263
  end
264
+ __require_text__(options[:sender_email], 'sender_email') if options.key?(:sender_email)
265
+ __https_url__(options[:webhook_url], 'webhook_url') if options.key?(:webhook_url)
266
+ %i[provider_ids seed_ids providers].each do |key|
267
+ next unless options.key?(key)
268
+
269
+ raise ArgumentError, "Invalid parameter: #{key} must be an array" unless options[key].is_a?(Array)
270
+ end
228
271
 
229
272
  body = { 'name' => name }
230
273
  {
@@ -235,6 +278,7 @@ module Zerobounce
235
278
  providers: 'providers',
236
279
  webhook_url: 'webhookUrl'
237
280
  }.each { |key, wire| body[wire] = options[key] if options.key?(key) }
281
+ body['testType'] = test_type if options.key?(:test_type)
238
282
 
239
283
  zb_request.ipt_request(:post, 'test', {}, json: body)
240
284
  end
@@ -244,14 +288,28 @@ module Zerobounce
244
288
  end
245
289
 
246
290
  def list_inbox_placement_tests(**options)
291
+ __check_options__(options, IPT_LIST_OPTIONS)
247
292
  params = {}
248
- params[:status] = options[:status] if options.key?(:status)
249
- params[:createdAfter] = options[:created_after] if options.key?(:created_after)
250
- params[:createdBefore] = options[:created_before] if options.key?(:created_before)
251
- params[:page] = options[:page] if options.key?(:page)
293
+ if options.key?(:status)
294
+ status = options[:status]
295
+ raise ArgumentError, 'status must be running or finished' unless INBOX_PLACEMENT_STATUSES.include?(status)
296
+
297
+ params[:status] = status
298
+ end
299
+ { created_after: :createdAfter, created_before: :createdBefore }.each do |key, wire|
300
+ params[wire] = __iso_date__(options[key], key.to_s) if options.key?(key)
301
+ end
302
+ if options.key?(:page)
303
+ page = options[:page]
304
+ raise ArgumentError, 'Invalid parameter: page must be an integer' unless page.is_a?(Integer)
305
+ raise ArgumentError, 'Invalid parameter: page (must be 1 or more)' if page < 1
306
+
307
+ params[:page] = page
308
+ end
252
309
  if options.key?(:page_size)
253
310
  page_size = options[:page_size]
254
- unless (INBOX_PLACEMENT_PAGE_SIZE_MIN..INBOX_PLACEMENT_PAGE_SIZE_MAX).cover?(page_size.to_i)
311
+ unless page_size.is_a?(Integer) &&
312
+ (INBOX_PLACEMENT_PAGE_SIZE_MIN..INBOX_PLACEMENT_PAGE_SIZE_MAX).cover?(page_size)
255
313
  raise ArgumentError,
256
314
  "page_size must be between #{INBOX_PLACEMENT_PAGE_SIZE_MIN} and #{INBOX_PLACEMENT_PAGE_SIZE_MAX}"
257
315
  end
@@ -276,6 +334,7 @@ module Zerobounce
276
334
  def set_inbox_placement_webhook(webhook_url)
277
335
  raise ArgumentError, 'webhook_url is required' if webhook_url.nil? || webhook_url.to_s.strip.empty?
278
336
 
337
+ __https_url__(webhook_url, 'webhook_url')
279
338
  zb_request.ipt_request(:put, 'webhook', {}, json: { 'webhookUrl' => webhook_url })
280
339
  end
281
340
 
@@ -287,19 +346,45 @@ module Zerobounce
287
346
  value.nil? || value.to_s.strip.empty?
288
347
  end
289
348
 
290
- # A boolean option, parsed strictly: true/false, 'true'/'false' in any
291
- # case, or 1/0. Anything else is an ArgumentError, so 'false' can no
292
- # longer be sent as true and a typo is not silently taken as a flag.
293
- def __strict_bool__(value, name)
294
- return value if [true, false].include?(value)
295
- return value == 1 if value.is_a?(Integer) && [0, 1].include?(value)
349
+ # A required text argument: a String with something in it, else an
350
+ # ArgumentError before anything is sent.
351
+ def __require_text__(value, name)
352
+ raise ArgumentError, "Empty parameter: #{name}" if value.nil? || (value.is_a?(String) && value.strip.empty?)
353
+ raise ArgumentError, "Invalid parameter: #{name} must be a string" unless value.is_a?(String)
354
+
355
+ value
356
+ end
357
+
358
+ # An optional text argument that is simply left out (nil) when it is nil
359
+ # or blank, and must be a String otherwise.
360
+ def __omit_blank__(value, name)
361
+ return nil if value.nil? || (value.is_a?(String) && value.strip.empty?)
362
+
363
+ __require_text__(value, name)
364
+ end
296
365
 
297
- if value.is_a?(String)
298
- text = value.strip.downcase
299
- return true if %w[true 1].include?(text)
300
- return false if %w[false 0].include?(text)
366
+ # A whole-number option in low..high seconds (nil is left to the caller).
367
+ def __whole_seconds__(value, name, low, high)
368
+ unless value.is_a?(Integer)
369
+ raise ArgumentError, "Invalid parameter: #{name} must be a whole number of seconds"
301
370
  end
302
- raise ArgumentError, "#{name} must be true or false"
371
+ return value if value >= low && value <= high
372
+
373
+ raise ArgumentError, "Invalid parameter: #{name} (must be between #{low} and #{high} seconds)"
374
+ end
375
+
376
+ # A column index: an Integer (not a boolean or a String) of 1 or more.
377
+ def __column__(value, name)
378
+ raise ArgumentError, "Empty parameter: #{name}" if value.nil?
379
+ raise ArgumentError, "Invalid parameter: #{name} must be an integer" unless value.is_a?(Integer)
380
+ raise ArgumentError, "Invalid parameter: #{name} (must be 1 or more)" if value < 1
381
+
382
+ value
383
+ end
384
+
385
+ # A boolean option, parsed strictly (see StrictBool).
386
+ def __strict_bool__(value, name)
387
+ StrictBool.parse(value, name)
303
388
  end
304
389
 
305
390
  # A strict boolean option as the string the API expects on the wire.
@@ -307,13 +392,14 @@ module Zerobounce
307
392
  __strict_bool__(value, name) ? 'true' : 'false'
308
393
  end
309
394
 
395
+ # An Integer, or a String of digits only ("2"), as callers have passed it; "2x" is refused.
310
396
  def __inbox_placement_test_type__(value)
311
- test_type = value.is_a?(Integer) ? value : value.to_s.strip.to_i
312
- unless INBOX_PLACEMENT_TEST_TYPES.include?(test_type)
397
+ value = value.to_i if value.is_a?(String) && value.match?(/\A\d+\z/)
398
+ unless value.is_a?(Integer) && INBOX_PLACEMENT_TEST_TYPES.include?(value)
313
399
  raise ArgumentError, "test_type must be one of #{INBOX_PLACEMENT_TEST_TYPES.join(', ')}"
314
400
  end
315
401
 
316
- test_type
402
+ value
317
403
  end
318
404
 
319
405
  # POSTs one of the eight documented S3 / SFTP file jobs on the bulkapi root.
@@ -325,10 +411,12 @@ module Zerobounce
325
411
  # docs list both as optional. Without either the API answers "This field is
326
412
  # required".
327
413
  def bulk_root_file_job(path, file_name, has_header_row, **options)
414
+ __check_options__(options, FILE_JOB_OPTIONS)
328
415
  raise ArgumentError, 'file_name is required' if __blank__(file_name)
329
416
  raise ArgumentError, 'return_url is required' if __blank__(options[:return_url])
330
417
 
331
- return_url = options[:return_url]
418
+ __require_text__(file_name, 'file_name')
419
+ return_url = __http_url__(options[:return_url], 'return_url')
332
420
 
333
421
  params = {
334
422
  has_header_row: __wire_bool__(has_header_row, 'has_header_row'),
@@ -342,6 +430,59 @@ module Zerobounce
342
430
  zb_request.bulk_root_form_post(path, params)
343
431
  end
344
432
 
433
+ # Unknown option keys are a typo, never silently dropped.
434
+ def __check_options__(options, known)
435
+ unknown = options.keys - known
436
+ return if unknown.empty?
437
+
438
+ raise ArgumentError, "Unknown option#{'s' if unknown.length > 1}: #{unknown.join(', ')} " \
439
+ "(known: #{known.join(', ')})"
440
+ end
441
+
442
+ def __check_filter__(rule, target, value)
443
+ if [rule, target, value].any? { |item| !item.is_a?(String) || item.strip.empty? }
444
+ raise ArgumentError, 'Empty parameter: rule, target, and value are required'
445
+ end
446
+ raise ArgumentError, 'Invalid parameter: rule (must be allow or block)' unless FILTER_RULES.include?(rule)
447
+ return if FILTER_TARGETS.include?(target)
448
+
449
+ raise ArgumentError, 'Invalid parameter: target (must be email, domain, mx or tld)'
450
+ end
451
+
452
+ # An http(s) URL with a host, as a String.
453
+ def __http_url__(value, name, schemes = %w[http https])
454
+ __require_text__(value, name)
455
+ uri = begin
456
+ URI.parse(value.strip)
457
+ rescue URI::InvalidURIError
458
+ nil
459
+ end
460
+ unless uri && schemes.include?(uri.scheme.to_s.downcase) && !uri.host.to_s.empty?
461
+ raise ArgumentError, "Invalid parameter: #{name} must be #{schemes.map { |x| "#{x}://" }.join(' or ')} URL"
462
+ end
463
+
464
+ value
465
+ end
466
+
467
+ def __https_url__(value, name)
468
+ __http_url__(value, name, %w[https])
469
+ end
470
+
471
+ # A strict YYYY-MM-DD date (or a Date/Time), as a string for the wire.
472
+ def __iso_date__(value, name)
473
+ return value.strftime('%Y-%m-%d') if value.is_a?(Date) || value.is_a?(Time)
474
+
475
+ if value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
476
+ begin
477
+ Date.strptime(value, '%Y-%m-%d')
478
+ return value
479
+ rescue ArgumentError
480
+ nil
481
+ end
482
+ end
483
+ raise ArgumentError, "Invalid parameter: #{name} must be a YYYY-MM-DD date"
484
+ end
485
+
345
486
  def inbox_placement_test_segment(test_id)
346
487
  raise ArgumentError, 'test_id is required' if test_id.nil? || test_id.to_s.strip.empty?
347
488