email-validation-sdk 1.0.0

data/lib/email_validation_sdk/client.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "uri"
+
+module EmailValidation
+  # Validated client settings. #inspect never shows the API key.
+  class Config
+    attr_reader :base_url, :timeout, :max_retries, :max_retry_wait
+
+    # No ASCII or Unicode whitespace (NBSP, U+2003, U+2028, BOM …).
+    KEY_PATTERN = /\A[^[:space:]\u{FEFF}]+\z/
+    private_constant :KEY_PATTERN
+
+    def initialize(api_key:, base_url: nil, timeout: 30, max_retries: 2, max_retry_wait: 10)
+      raise ArgumentError, "api_key is required (a non-empty key without whitespace)" unless valid_key?(api_key)
+
+      url = (base_url || DEFAULT_BASE_URL).to_s
+      raise ArgumentError, "base_url must start with http:// or https://" unless url.start_with?("https://", "http://")
+      raise ArgumentError, "timeout must be a number of seconds greater than 0" unless
+        timeout.is_a?(Numeric) && timeout.positive?
+
+      @api_key = api_key.dup.freeze
+      @base_url = url.sub(%r{/+\z}, "").freeze
+      @timeout = timeout
+      @max_retries = [Integer(max_retries), 0].max
+      @max_retry_wait = [max_retry_wait.to_f, 0.0].max
+      freeze
+    end
+
+    # @api private
+    def authorization
+      "Bearer #{@api_key}"
+    end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{base_url.inspect} timeout=#{timeout} max_retries=#{max_retries} " \
+        "max_retry_wait=#{max_retry_wait} api_key=[hidden]>"
+    end
+    alias to_s inspect
+
+    def pretty_print(pp)
+      pp.text(inspect)
+    end
+
+    private
+
+    # A key in another encoding (or with invalid bytes) is refused with the same ArgumentError, never an
+    # Encoding error.
+    def valid_key?(api_key)
+      return false unless api_key.is_a?(String)
+
+      key = api_key.encoding == Encoding::UTF_8 ? api_key : api_key.dup.force_encoding(Encoding::UTF_8)
+      key.valid_encoding? && KEY_PATTERN.match?(key)
+    end
+  end
+
+  # Client for the email-validation.org REST API.
+  #
+  #   client = EmailValidation::Client.new(api_key: ENV.fetch("EV_API_KEY"))
+  #   result = client.validate("accepted@sandbox.email-validation.org")
+  #   result.status # => "valid"
+  #
+  # Retries: answers 429 and 503 are never charged, so they are retried for every method with backoff (honouring
+  # +Retry-After+) up to +max_retries+ times, unless the wait would be longer than +max_retry_wait+ seconds (and never
+  # for +key_daily_cap+). Network failures and timeouts are retried only for GET: a check that reached the service may
+  # already have been charged.
+  #
+  # The client is safe to share between threads; build it once and reuse it.
+  class Client
+    USER_AGENT = "email-validation-ruby/#{VERSION} (ruby #{RUBY_VERSION})".freeze
+    JSON_TYPE = "application/json"
+    RETRY_STATUSES = [429, 503].freeze
+    NO_RETRY_CODES = ["key_daily_cap"].freeze
+    private_constant :JSON_TYPE, :RETRY_STATUSES, :NO_RETRY_CODES
+
+    # Settings (base URL, timeout, retries); the key is never shown.
+    attr_reader :config
+
+    # Bulk jobs: +client.bulk.create+, +get+, +start+, +cancel+, +results+, +wait+.
+    attr_reader :bulk
+
+    # Options:
+    # - +api_key+ (required): your key (+ev_live_…+). Keep it on the server.
+    # - +base_url+: default +https://api.email-validation.org+.
+    # - +timeout+: seconds per attempt (connect and the whole response), default 30. A check may take up to 15 s on
+    #   our side, so keep it a few seconds above the +timeout+ you pass to #validate.
+    # - +max_retries+: retries after the first attempt, default 2 (negative values count as 0).
+    # - +max_retry_wait+: the longest single wait in seconds the client accepts before giving up, default 10.
+    # - +transport+: replaces the HTTP stack (see NetHttpTransport); a transport you pass is never closed by #close.
+    # - +sleep+, +clock+: injectable for tests (+sleep.call(seconds)+; +clock.call+ returns the current Time).
+    def initialize(api_key:, base_url: nil, timeout: 30, max_retries: 2, max_retry_wait: 10, transport: nil,
+                   sleep: nil, clock: nil)
+      @config = Config.new(api_key: api_key, base_url: base_url, timeout: timeout, max_retries: max_retries,
+                           max_retry_wait: max_retry_wait)
+      @owns_transport = transport.nil?
+      @transport = transport || NetHttpTransport.new
+      @sleep = sleep || ->(seconds) { Kernel.sleep(seconds) }
+      @clock = clock || -> { Time.now }
+      @bulk = Bulk.new(self)
+    end
+
+    # Checks one address and returns a ValidationResult. Costs 1 credit unless the result is +unknown+ or the answer
+    # is local (malformed and sandbox addresses are free).
+    #
+    # - +ip_address+: the address the signup came from (optional).
+    # - +timeout+: seconds the service may spend on the check (5–15, server default 15). This is not the client's
+    #   per-attempt timeout, which should stay a few seconds above it.
+    # - +fresh+: +true+ checks the address again even when it was checked in the last 12 months (by default the
+    #   earlier definite result may be returned; +processed_at+ is when the answer was produced).
+    #
+    # A validation is never retried after a network failure or timeout (it may already have been charged).
+    def validate(email, ip_address: nil, timeout: nil, fresh: nil)
+      raise ArgumentError, "email must be a String" unless email.is_a?(String)
+
+      body = { "email" => email, "ip_address" => ip_address, "timeout" => timeout, "fresh" => fresh }.compact
+      request_model(ValidationResult, "POST", "/v1/validate", json: body)
+    end
+
+    # Balance, debt, pending credits and credit lots (soonest-expiring first).
+    def credits
+      request_model(Credits, "GET", "/v1/credits")
+    end
+
+    # Credit usage by day (default) or by API key (+group_by: "key"+). Dates are +"YYYY-MM-DD"+ strings (UTC) or
+    # Date objects.
+    def usage(from: nil, to: nil, group_by: nil)
+      query = { "from" => from, "to" => to, "group_by" => group_by }
+      request_model(UsageResponse, "GET", "/v1/usage", query: query)
+    end
+
+    # The public service status (overall and per component).
+    def status
+      request_model(ServiceStatus, "GET", "/v1/status")
+    end
+
+    # Releases the HTTP connections of the built-in transport. A transport you passed in is left open.
+    def close
+      @transport.close if @owns_transport && @transport.respond_to?(:close)
+      nil
+    end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{config.base_url.inspect} timeout=#{config.timeout} " \
+        "max_retries=#{config.max_retries} api_key=[hidden]>"
+    end
+    alias to_s inspect
+
+    def pretty_print(pp)
+      pp.text(inspect)
+    end
+
+    # @api private
+    def request_model(model, method, path, **options)
+      model.from_h(decode_json(perform(method, path, **options)))
+    end
+
+    # @api private
+    def sleep_for(seconds)
+      @sleep.call(seconds)
+    end
+
+    # @api private
+    # Sends one call with the retry policy and returns the 2xx HttpResponse. +stream+, when given, is an object with
+    # +on_head(status, headers)+ (passed to the transport as its block) and +started?+ (true once a chunk reached the
+    # caller, after which nothing is retried).
+    def perform(method, path, query: nil, json: nil, body: nil, content_type: nil, accept: JSON_TYPE, headers: nil,
+                stream: nil)
+      request = build_request(method, path, query, json, body, content_type, accept, headers)
+      attempt = 0
+      loop do
+        begin
+          response = stream ? @transport.call(request) { |s, h| stream.on_head(s, h) } : @transport.call(request)
+        rescue TransportError => e
+          if method == "GET" && attempt < config.max_retries && !stream&.started?
+            sleep_for(backoff(attempt))
+            attempt += 1
+            next
+          end
+          raise connection_error(e)
+        end
+        return response if (200..299).cover?(response.status)
+
+        error = error_from(response)
+        wait = retry_wait(error, attempt)
+        raise error if wait.nil?
+
+        sleep_for(wait)
+        attempt += 1
+      end
+    end
+
+    # @api private
+    def parse_retry_after(value)
+      return nil if value.nil?
+
+      value = value.strip
+      return Integer(value, 10) if value.match?(/\A\d+\z/)
+
+      begin
+        at = Time.httpdate(value)
+      rescue ArgumentError
+        return nil
+      end
+      [(at - @clock.call).ceil, 0].max
+    end
+
+    private
+
+    def build_request(method, path, query, json, body, content_type, accept, extra_headers)
+      url = config.base_url + path
+      encoded = encode_query(query)
+      url = "#{url}?#{encoded}" unless encoded.empty?
+      headers = { "authorization" => config.authorization, "accept" => accept, "user-agent" => USER_AGENT }
+      if json
+        body = JSON.generate(json).b
+        headers["content-type"] = JSON_TYPE
+      elsif body
+        body = body.b
+        headers["content-type"] = content_type if content_type
+      end
+      extra_headers&.each { |name, value| headers[name.to_s.downcase] = value.to_s }
+      HttpRequest.new(method: method, url: url, headers: headers, body: body, timeout: config.timeout)
+    end
+
+    def encode_query(query)
+      return "" if query.nil?
+
+      pairs = query.filter_map do |name, value|
+        next if value.nil?
+
+        [name.to_s, value.to_s] # true/false become "true"/"false"; integers decimal; Dates ISO 8601
+      end
+      URI.encode_www_form(pairs)
+    end
+
+    def decode_json(response)
+      parsed = JSON.parse(response.body.dup.force_encoding(Encoding::UTF_8))
+      raise JSON::ParserError, "not an object" unless parsed.is_a?(Hash)
+
+      parsed
+    rescue JSON::ParserError, EncodingError
+      raise Error.new("The API answered with something other than JSON.", status: response.status,
+                                                                           code: "unexpected_response",
+                                                                           request_id: response.header("x-request-id"))
+    end
+
+    def error_from(response)
+      request_id = response.header("x-request-id")
+      retry_after = parse_retry_after(response.header("retry-after"))
+      klass = EmailValidation.error_class_for_status(response.status)
+      envelope = begin
+        JSON.parse(response.body.dup.force_encoding(Encoding::UTF_8))
+      rescue JSON::ParserError, EncodingError
+        nil
+      end
+      err = envelope.is_a?(Hash) ? envelope["error"] : nil
+      if err.is_a?(Hash) && ERROR_CODES.include?(err["code"])
+        code = err["code"]
+        message = err["message"].is_a?(String) ? err["message"] : code
+        request_id = err["request_id"] if err["request_id"].is_a?(String)
+      else
+        code = "unexpected_response"
+        message = "Unexpected HTTP #{response.status} from the API."
+      end
+      klass.new(message, status: response.status, code: code, request_id: request_id, retry_after: retry_after)
+    end
+
+    def retry_wait(error, attempt)
+      return nil unless RETRY_STATUSES.include?(error.status)
+      return nil if NO_RETRY_CODES.include?(error.code) || attempt >= config.max_retries
+
+      wait = error.retry_after.nil? ? backoff(attempt) : error.retry_after
+      wait <= config.max_retry_wait ? wait : nil
+    end
+
+    # Exponential backoff with jitter: 0.25–0.5 s, 0.5–1 s, 1–2 s … capped at 4–8 s.
+    def backoff(attempt)
+      base = [8.0, 0.5 * (2**attempt)].min
+      (base / 2) + (rand * base / 2)
+    end
+
+    def connection_error(transport_error)
+      if transport_error.timeout?
+        ConnectionError.new("The request timed out.", status: 0, code: "timeout")
+      else
+        ConnectionError.new("The API could not be reached.", status: 0, code: "connection_error")
+      end
+    end
+  end
+end

data/lib/email_validation_sdk/constants.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module EmailValidation
+  # Public vocabulary of the email-validation.org API.
+  #
+  # Every value is a plain String: results keep the raw string even when a newer API version sends a value this SDK
+  # does not list yet (forward compatibility), so compare with the constants below rather than with a closed enum.
+
+  DEFAULT_BASE_URL = "https://api.email-validation.org"
+
+  # EU data residency: validated and stored in the EU. Pass it as +base_url:+ to use the EU endpoint.
+  EU_BASE_URL = "https://api-eu.email-validation.org"
+
+  # Free test addresses: +<reason>@sandbox.email-validation.org+ answers that reason and costs nothing.
+  SANDBOX_DOMAIN = "sandbox.email-validation.org"
+
+  # Default webhook timestamp tolerance, in seconds.
+  DEFAULT_WEBHOOK_TOLERANCE = 300
+
+  STATUSES = %w[valid invalid catch_all unknown disposable].freeze
+
+  REASONS_BY_STATUS = {
+    "valid" => %w[
+      accepted alias normalized low_engagement high_engagement trusted_catch_all ai_agent role_account abuse_linked
+      suppressed trap_pattern spamtrap complainer
+    ].freeze,
+    "invalid" => %w[no_mailbox no_inbound_mail invalid_syntax likely_typo no_dns mailbox_full unroutable].freeze,
+    "catch_all" => %w[catch_all role_catch_all forwarding_domain].freeze,
+    "unknown" => %w[server_unavailable temporary_error greylisted anti_spam_block timeout internal_error].freeze,
+    "disposable" => %w[disposable].freeze
+  }.freeze
+
+  # Catalogue order: by status, unknown last.
+  REASONS = %w[valid invalid catch_all disposable unknown].flat_map { |s| REASONS_BY_STATUS[s] }.freeze
+
+  ACTIONS = %w[send send_with_caution remove retry_later].freeze
+
+  # The fixed status and action of every reason.
+  REASON_INFO = {
+    "accepted" => %w[valid send], "alias" => %w[valid send], "normalized" => %w[valid send],
+    "low_engagement" => %w[valid send_with_caution], "high_engagement" => %w[valid send],
+    "trusted_catch_all" => %w[valid send], "ai_agent" => %w[valid send_with_caution],
+    "role_account" => %w[valid send_with_caution], "abuse_linked" => %w[valid remove],
+    "suppressed" => %w[valid remove], "trap_pattern" => %w[valid remove], "spamtrap" => %w[valid remove],
+    "complainer" => %w[valid remove],
+    "no_mailbox" => %w[invalid remove], "no_inbound_mail" => %w[invalid remove],
+    "invalid_syntax" => %w[invalid remove], "likely_typo" => %w[invalid remove], "no_dns" => %w[invalid remove],
+    "mailbox_full" => %w[invalid remove], "unroutable" => %w[invalid remove],
+    "catch_all" => %w[catch_all send_with_caution], "role_catch_all" => %w[catch_all send_with_caution],
+    "forwarding_domain" => %w[catch_all send_with_caution],
+    "disposable" => %w[disposable remove],
+    "server_unavailable" => %w[unknown retry_later], "temporary_error" => %w[unknown retry_later],
+    "greylisted" => %w[unknown retry_later], "anti_spam_block" => %w[unknown retry_later],
+    "timeout" => %w[unknown retry_later], "internal_error" => %w[unknown retry_later]
+  }.transform_values { |(status, action)| { status: status, action: action }.freeze }.freeze
+
+  SMTP_PROVIDERS = %w[
+    google microsoft yahoo apple zoho proton fastmail gmx yandex mailru amazon mimecast proofpoint barracuda other
+  ].freeze
+
+  BULK_JOB_STATUSES = %w[
+    analyzing ready queued running cancelling finalizing completed failed cancelled expired
+  ].freeze
+
+  TERMINAL_BULK_JOB_STATUSES = %w[completed failed cancelled expired].freeze
+
+  # Why a bulk job +failed+ or waits in +ready+ (its +error_code+), mapped to the job status it comes with.
+  BULK_JOB_ERROR_CODES = {
+    "invalid_csv" => "failed", "too_many_rows" => "failed", "empty_file" => "failed",
+    "email_column_not_found" => "failed", "upload_missing" => "failed", "pipeline_mismatch" => "failed",
+    "missing_results" => "failed", "internal_error" => "failed",
+    "insufficient_credits" => "ready", "upstream_capacity" => "ready", "account_suspended" => "ready",
+    "billing_hold" => "ready", "invalid_key" => "ready", "forbidden_scope" => "ready",
+    "key_daily_cap" => "ready", "upload_expired" => "ready"
+  }.freeze
+
+  # API error codes, in the API's order. Branch on these (or on the error class), never on messages.
+  ERROR_CODES = %w[
+    invalid_request unauthorized insufficient_credits forbidden forbidden_origin not_found conflict length_required
+    payload_too_large rate_limited abuse_throttled key_daily_cap internal_error service_unavailable upstream_capacity
+  ].freeze
+
+  # Codes the client itself uses when it got no usable answer.
+  CLIENT_ERROR_CODES = %w[connection_error timeout unexpected_response aborted].freeze
+
+  # Every +type+ a webhook delivery can carry; +webhook.test+ is sent only by "Send test" in the dashboard.
+  WEBHOOK_EVENTS = %w[bulk.completed bulk.failed credits.low credits.expiring webhook.test].freeze
+
+  # Named constants: +EmailValidation::Status::VALID+, +Reason::CATCH_ALL+, +Action::SEND_WITH_CAUTION+,
+  # +SmtpProvider::GOOGLE+, +BulkJobStatus::COMPLETED+, +ErrorCode::RATE_LIMITED+, +WebhookEventType::BULK_COMPLETED+ …
+  module Status; end
+  module Reason; end
+  module Action; end
+  module SmtpProvider; end
+  module BulkJobStatus; end
+  module ErrorCode; end
+  module WebhookEventType; end
+
+  {
+    Status => STATUSES, Reason => REASONS, Action => ACTIONS, SmtpProvider => SMTP_PROVIDERS,
+    BulkJobStatus => BULK_JOB_STATUSES, ErrorCode => ERROR_CODES + CLIENT_ERROR_CODES,
+    WebhookEventType => WEBHOOK_EVENTS
+  }.each do |mod, values|
+    values.each do |value|
+      name = value.upcase.tr(".", "_")
+      mod.const_set(name, value) unless mod.const_defined?(name, false)
+    end
+    mod.freeze
+  end
+
+  module_function
+
+  # True when +value+ is one of the five result statuses.
+  def status?(value)
+    STATUSES.include?(value)
+  end
+
+  # True when +value+ is a known reason.
+  def reason?(value)
+    REASONS.include?(value)
+  end
+
+  # +<reason>@sandbox.email-validation.org+: a free test address that answers +reason+.
+  # Raises ArgumentError for an unknown reason.
+  def sandbox_address(reason)
+    reason = reason.to_s
+    raise ArgumentError, "unknown reason: #{reason.inspect}" unless reason?(reason)
+
+    "#{reason}@#{SANDBOX_DOMAIN}"
+  end
+end

data/lib/email_validation_sdk/errors.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module EmailValidation
+  # Base class of every error the client raises. Branch on the class or on #code, never on #message.
+  #
+  # Raised directly only when a 2xx answer is not JSON (code +unexpected_response+).
+  #
+  # Attributes:
+  # - +status+: the HTTP status, or 0 when no answer arrived (or the SDK refused the call before sending).
+  # - +code+: an API error code (+insufficient_credits+, +rate_limited+ …) or a client code (+connection_error+,
+  #   +timeout+, +unexpected_response+, +aborted+).
+  # - +request_id+: our id for the request (quote it to support), when the API answered.
+  # - +retry_after+: whole seconds from the +Retry-After+ header, or nil.
+  # - +cause+: the underlying exception, when there is one (Ruby sets it automatically).
+  class Error < StandardError
+    attr_reader :status, :code, :request_id, :retry_after
+
+    def initialize(message = nil, status: 0, code: "unexpected_response", request_id: nil, retry_after: nil)
+      super(message || code)
+      @status = status
+      @code = code
+      @request_id = request_id
+      @retry_after = retry_after
+    end
+
+    # The canonical kind name, e.g. "RateLimitError" (the class name without the module).
+    def kind
+      self.class.name.split("::").last
+    end
+
+    # Shown for uncaught errors: kind, status, code and request id. Never the key, the body or the checked address.
+    def detailed_message(highlight: false, **)
+      "#{message} (#{self.class.name}: status=#{status} code=#{code} request_id=#{request_id || "-"})"
+    end
+
+    def inspect
+      "#<#{self.class.name} status=#{status} code=#{code.inspect} request_id=#{request_id.inspect} " \
+        "retry_after=#{retry_after.inspect} message=#{message.inspect}>"
+    end
+  end
+
+  # The canonical name of the base kind.
+  EmailValidationError = Error
+
+  # 400, 411, 413, any other 4xx without its own class, checks refused before sending (status 0), and a ranged
+  # download answered without 206: fix the request.
+  class InvalidRequestError < Error; end
+
+  # 401: missing, malformed, revoked or rolled key.
+  class AuthenticationError < Error; end
+
+  # 402: not enough credits. Nothing was charged.
+  class InsufficientCreditsError < Error; end
+
+  # 403: missing scope, disallowed origin, suspended account or billing hold.
+  class PermissionDeniedError < Error; end
+
+  # 404: no such resource for this account.
+  class NotFoundError < Error; end
+
+  # 409: the resource is in the wrong state.
+  class ConflictError < Error; end
+
+  # 429: slow down. Retried automatically when the wait is short (except +key_daily_cap+).
+  class RateLimitError < Error; end
+
+  # 503: temporarily unavailable, nothing charged. Retried automatically like 429.
+  class ServiceUnavailableError < Error; end
+
+  # 500, any other status >= 500 and any other unexpected status (e.g. a 3xx redirect, which is never followed).
+  class ServerError < Error; end
+
+  # No HTTP answer: network failure (+connection_error+), attempt timeout (+timeout+), or a #wait deadline
+  # (+timeout+). Status is 0.
+  class ConnectionError < Error; end
+
+  # A webhook delivery failed a header, timestamp, secret or signature check. Not part of the Error family.
+  class WebhookVerificationError < StandardError; end
+
+  # @api private
+  ERRORS_BY_STATUS = {
+    400 => InvalidRequestError, 401 => AuthenticationError, 402 => InsufficientCreditsError,
+    403 => PermissionDeniedError, 404 => NotFoundError, 409 => ConflictError, 411 => InvalidRequestError,
+    413 => InvalidRequestError, 429 => RateLimitError, 503 => ServiceUnavailableError
+  }.freeze
+  private_constant :ERRORS_BY_STATUS
+
+  # @api private
+  def self.error_class_for_status(status)
+    ERRORS_BY_STATUS.fetch(status) { (400..499).cover?(status) ? InvalidRequestError : ServerError }
+  end
+end