email-validation-sdk 1.0.0

data/lib/email_validation_sdk/models.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "json"
+
+module EmailValidation
+  # Shared behaviour of the response models (immutable +Data+ classes).
+  #
+  # - +Model.from_h(hash)+ decodes the API's JSON object (string or symbol keys). Unknown fields are ignored and
+  #   unknown enum values are kept as the raw string, so a newer API never breaks decoding.
+  # - +#to_h+ returns the API's field names (as symbols) with nested models converted and +nil+ kept;
+  #   +#to_json+ re-encodes the API's JSON.
+  module Model
+    # @api private
+    module ClassMethods
+      def from_h(hash)
+        raise ArgumentError, "#{name} expects a Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+        values = members.to_h do |member|
+          raw = hash.key?(member.to_s) ? hash[member.to_s] : hash[member]
+          [member, decode_member(member, raw, hash)]
+        end
+        new(**values)
+      end
+
+      private
+
+      # Overridden by models with nested fields.
+      def decode_member(_member, raw, _hash)
+        raw
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def self.deep(value)
+      case value
+      when Model then value.to_h
+      when Array then value.map { |v| deep(v) }
+      when Hash then value.transform_values { |v| deep(v) }
+      else value
+      end
+    end
+
+    def to_h
+      super.transform_values { |v| Model.deep(v) }
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+
+  # Counts by result status. In bulk jobs and webhook events the object is partial (only the statuses seen so far),
+  # so absent statuses are nil and are left out again by #to_h.
+  StatusCounts = Data.define(:valid, :invalid, :catch_all, :unknown, :disposable) do
+    include Model
+
+    def to_h
+      super.compact
+    end
+  end
+
+  # The result of one check (+POST /v1/validate+). Fields in the API's order.
+  ValidationResult = Data.define(
+    :email, :status, :reason, :action, :account, :domain, :did_you_mean, :free_email, :role_account, :disposable,
+    :catch_all_domain, :mx_found, :mx_record, :smtp_provider, :domain_age_days, :processed_at, :credits_used,
+    :request_id
+  ) do
+    include Model
+  end
+
+  # One lot of purchased credits.
+  CreditLot = Data.define(:remaining, :expires_at) do
+    include Model
+  end
+
+  # +GET /v1/credits+: balance, debt, pending credits and lots (soonest-expiring first).
+  Credits = Data.define(:balance, :debt, :pending, :lots) do
+    include Model
+
+    def self.decode_member(member, raw, _hash)
+      member == :lots && raw.is_a?(Array) ? raw.map { |lot| CreditLot.from_h(lot) } : raw
+    end
+    private_class_method :decode_member
+  end
+
+  # Usage totals for the period.
+  UsageTotals = Data.define(:credits_used, :by_status) do
+    include Model
+
+    def self.decode_member(member, raw, _hash)
+      member == :by_status && raw.is_a?(Hash) ? StatusCounts.from_h(raw) : raw
+    end
+    private_class_method :decode_member
+  end
+
+  # One day of usage (+group_by: "day"+). +by_status+ is approximate.
+  UsageDay = Data.define(:date, :credits_used, :by_status) do
+    include Model
+
+    def self.decode_member(member, raw, _hash)
+      member == :by_status && raw.is_a?(Hash) ? StatusCounts.from_h(raw) : raw
+    end
+    private_class_method :decode_member
+  end
+
+  # Usage of one API key (+group_by: "key"+). +name+ and +last4+ are nil for a deleted key.
+  UsageByKey = Data.define(:key_id, :name, :last4, :credits_used) do
+    include Model
+  end
+
+  # +GET /v1/usage+. +items+ holds UsageDay values when +group_by+ is "day" and UsageByKey values when "key".
+  UsageResponse = Data.define(:from, :to, :group_by, :totals, :items) do
+    include Model
+
+    def self.decode_member(member, raw, hash)
+      case member
+      when :totals then raw.is_a?(Hash) ? UsageTotals.from_h(raw) : raw
+      when :items
+        return raw unless raw.is_a?(Array)
+
+        group_by = hash["group_by"] || hash[:group_by]
+        item_class = { "day" => UsageDay, "key" => UsageByKey }[group_by]
+        item_class ? raw.map { |item| item_class.from_h(item) } : raw
+      else raw
+      end
+    end
+    private_class_method :decode_member
+  end
+
+  # A bulk job. Fields in the API's order; the counters from +total_rows+ to +local_answered+ are nil while the job
+  # is +analyzing+.
+  BulkJob = Data.define(
+    :id, :status, :filename, :total_rows, :unique_emails, :duplicates, :syntax_invalid, :local_answered, :processed,
+    :credits_reserved, :credits_charged, :counts, :error_code, :webhook_endpoint_id, :created_at, :started_at,
+    :finished_at, :expires_at
+  ) do
+    include Model
+
+    def self.decode_member(member, raw, _hash)
+      member == :counts && raw.is_a?(Hash) ? StatusCounts.from_h(raw) : raw
+    end
+    private_class_method :decode_member
+
+    # Completed, failed, cancelled or expired: the job will not change any more.
+    def terminal?
+      TERMINAL_BULK_JOB_STATUSES.include?(status)
+    end
+
+    # In +ready+ with an +error_code+: its start was refused (e.g. +insufficient_credits+) and it never moves on.
+    def stuck?
+      status == "ready" && error_code.is_a?(String) && !error_code.empty?
+    end
+  end
+
+  # The state of each public component.
+  ServiceComponents = Data.define(:website, :api, :bulk, :sign_in, :payments, :support) do
+    include Model
+  end
+
+  # +GET /v1/status+. Each state is "operational", "degraded" or "outage".
+  ServiceStatus = Data.define(:status, :components, :updated_at) do
+    include Model
+
+    def self.decode_member(member, raw, _hash)
+      member == :components && raw.is_a?(Hash) ? ServiceComponents.from_h(raw) : raw
+    end
+    private_class_method :decode_member
+  end
+
+  # +data+ of +bulk.completed+ and +bulk.failed+ events.
+  BulkEventData = Data.define(
+    :job_id, :status, :total_rows, :unique_emails, :processed, :credits_charged, :counts, :error_code
+  ) do
+    include Model
+
+    def self.decode_member(member, raw, _hash)
+      member == :counts && raw.is_a?(Hash) ? StatusCounts.from_h(raw) : raw
+    end
+    private_class_method :decode_member
+  end
+
+  # +data+ of +credits.low+ events.
+  CreditsLowData = Data.define(:balance, :threshold) do
+    include Model
+  end
+
+  # +data+ of +credits.expiring+ events.
+  CreditsExpiringData = Data.define(:credits, :expires_at) do
+    include Model
+  end
+
+  # +data+ of +webhook.test+ events (sent by "Send test" in the dashboard).
+  WebhookTestData = Data.define(:endpoint_id) do
+    include Model
+  end
+
+  WEBHOOK_DATA_CLASSES = {
+    "bulk.completed" => BulkEventData, "bulk.failed" => BulkEventData, "credits.low" => CreditsLowData,
+    "credits.expiring" => CreditsExpiringData, "webhook.test" => WebhookTestData
+  }.freeze
+  private_constant :WEBHOOK_DATA_CLASSES
+
+  # A verified webhook delivery. +data+ is a typed model for the known event types and the raw Hash (string keys)
+  # for a type this SDK does not know yet.
+  WebhookEvent = Data.define(:type, :timestamp, :data) do
+    include Model
+
+    def self.decode_member(member, raw, hash)
+      return raw unless member == :data && raw.is_a?(Hash)
+
+      data_class = WEBHOOK_DATA_CLASSES[hash["type"] || hash[:type]]
+      data_class ? data_class.from_h(raw) : raw
+    end
+    private_class_method :decode_member
+  end
+end

data/lib/email_validation_sdk/transport.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "timeout"
+require "uri"
+
+module EmailValidation
+  # One HTTP request as the client hands it to a transport.
+  #
+  # #inspect and #to_s hide the headers (they carry the API key) and the body (it carries the checked address).
+  class HttpRequest
+    attr_reader :method, :url, :headers, :body, :timeout
+
+    # +headers+ is a Hash with lower-case names; +body+ is a binary String or nil; +timeout+ is seconds per attempt.
+    def initialize(method:, url:, headers:, body:, timeout:)
+      @method = method
+      @url = url
+      @headers = headers.freeze
+      @body = body&.freeze
+      @timeout = timeout
+      freeze
+    end
+
+    def inspect
+      "#<#{self.class.name} #{method} #{url} headers=[hidden] body=[hidden]>"
+    end
+    alias to_s inspect
+
+    def pretty_print(pp)
+      pp.text(inspect)
+    end
+  end
+
+  # One HTTP answer as a transport hands it back. +headers+ is a Hash with lower-case names (several values joined
+  # with ", "); +body+ is a binary String ("" when the body was streamed to a sink).
+  class HttpResponse
+    attr_reader :status, :headers, :body
+
+    def initialize(status:, headers: {}, body: "")
+      @status = Integer(status)
+      @headers = headers.to_h { |k, v| [k.to_s.downcase, v.to_s] }.freeze
+      @body = (body || "").b.freeze
+      freeze
+    end
+
+    # The value of a header (any case), or nil.
+    def header(name)
+      headers[name.to_s.downcase]
+    end
+
+    def inspect
+      "#<#{self.class.name} status=#{status} bytes=#{body.bytesize}>"
+    end
+  end
+
+  # Raised by a transport when a request got no HTTP answer. #timeout? tells a timeout from a network failure.
+  class TransportError < StandardError
+    def initialize(message = "The API could not be reached.", timeout: false)
+      super(message)
+      @timeout = timeout
+    end
+
+    def timeout?
+      @timeout
+    end
+  end
+
+  # The default transport, on the standard library's Net::HTTP. Redirects are never followed (Net::HTTP does not
+  # follow them), connections are kept alive and reused across threads through a small pool, and the client's
+  # +timeout+ bounds every attempt (connect, TLS, request and the whole response).
+  #
+  # A transport is any object with +call(request)+ returning an HttpResponse (raise TransportError when no answer
+  # arrives). Optional streaming: when +call+ is given a block, the transport calls it once with
+  # +(status, headers)+ as soon as the response head arrives; if the block returns a callable, the transport passes
+  # each body chunk to it (instead of buffering the body) and returns an HttpResponse with an empty body.
+  class NetHttpTransport
+    NETWORK_ERRORS = [
+      IOError, EOFError, SocketError, SystemCallError, OpenSSL::SSL::SSLError, Net::ProtocolError,
+      Net::HTTPBadResponse, Zlib::Error
+    ].freeze
+    TIMEOUT_ERRORS = [Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Timeout::Error].freeze
+    private_constant :NETWORK_ERRORS, :TIMEOUT_ERRORS
+
+    # Raised by the attempt deadline. A private class outside StandardError, so neither a timeout raised by other
+    # code nor a +rescue => e+ in a results block can be confused with it or swallow it.
+    class AttemptTimeout < Exception; end # rubocop:disable Lint/InheritException
+    private_constant :AttemptTimeout
+
+    # +max_idle+: idle connections kept per host. +keep_alive_timeout+: seconds an idle connection may be reused.
+    def initialize(max_idle: 8, keep_alive_timeout: 15)
+      @max_idle = max_idle
+      @keep_alive_timeout = keep_alive_timeout
+      @idle = Hash.new { |h, k| h[k] = [] }
+      @lock = Mutex.new
+      @closed = false
+    end
+
+    def call(request, &on_head)
+      uri = URI.parse(request.url)
+      conn = nil
+      reusable = false
+      begin
+        response = Timeout.timeout(request.timeout, AttemptTimeout) do
+          conn = checkout(uri, request.timeout)
+          exchange(conn, uri, request, on_head)
+        end
+        reusable = true
+        response
+      rescue AttemptTimeout, *TIMEOUT_ERRORS
+        raise TransportError.new("The request timed out.", timeout: true)
+      rescue *NETWORK_ERRORS
+        raise TransportError, "The API could not be reached."
+      ensure
+        reusable ? checkin(uri, conn) : discard(conn)
+      end
+    end
+
+    # Closes the idle connections. Safe to call more than once.
+    def close
+      conns = @lock.synchronize do
+        @closed = true
+        all = @idle.values.flatten
+        @idle.clear
+        all
+      end
+      conns.each { |c| discard(c) }
+      nil
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    private
+
+    def exchange(conn, uri, request, on_head)
+      req = build_request(uri, request)
+      status = nil
+      headers = nil
+      body = nil
+      conn.request(req) do |res|
+        status = res.code.to_i
+        headers = {}
+        res.each_header { |name, value| headers[name] = value }
+        sink = on_head&.call(status, headers)
+        if sink
+          res.read_body { |chunk| sink.call(chunk) }
+          body = ""
+        else
+          body = res.read_body.to_s
+        end
+      end
+      HttpResponse.new(status: status, headers: headers, body: body)
+    end
+
+    def build_request(uri, request)
+      has_body = !request.body.nil?
+      # Net::HTTPGenericRequest lets a body-less POST go out without a body or a default Content-Type.
+      req = Net::HTTPGenericRequest.new(request.method, has_body, true, uri, request.headers.dup)
+      req.body = request.body if has_body
+      req
+    end
+
+    def checkout(uri, timeout)
+      key = pool_key(uri)
+      conn = @lock.synchronize { @idle[key].pop }
+      return configure(conn, timeout) if conn&.started?
+
+      conn = Net::HTTP.new(uri.host, uri.port)
+      conn.use_ssl = uri.scheme == "https"
+      conn.max_retries = 0 # the client owns the retry policy (a POST that reached us may have been charged)
+      conn.keep_alive_timeout = @keep_alive_timeout
+      configure(conn, timeout)
+      conn.start
+      conn
+    end
+
+    def configure(conn, timeout)
+      conn.open_timeout = timeout
+      conn.read_timeout = timeout
+      conn.write_timeout = timeout
+      conn.ssl_timeout = timeout if conn.use_ssl?
+      conn
+    end
+
+    def checkin(uri, conn)
+      keep = @lock.synchronize do
+        list = @idle[pool_key(uri)]
+        next false if @closed || list.size >= @max_idle
+
+        list.push(conn)
+        true
+      end
+      discard(conn) unless keep
+    end
+
+    def discard(conn)
+      conn.finish if conn&.started?
+    rescue StandardError
+      nil
+    end
+
+    def pool_key(uri)
+      "#{uri.scheme}://#{uri.host}:#{uri.port}"
+    end
+  end
+end

data/lib/email_validation_sdk/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module EmailValidation
+  # SDK version (Semantic Versioning). Sent in the User-Agent header.
+  VERSION = "1.0.0"
+end

data/lib/email_validation_sdk/webhooks.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module EmailValidation
+  # Webhook signature verification (Standard Webhooks scheme).
+  #
+  # Signed content: +<webhook-id>.<webhook-timestamp>.<raw body>+, HMAC-SHA256 with the endpoint secret (the part
+  # after +whsec_+, base64-decoded); header +webhook-signature: v1,<base64> [v1,<base64> …]+.
+  module Webhooks
+    MISSING_HEADERS = "Missing webhook headers."
+    INVALID_TIMESTAMP = "Invalid webhook timestamp."
+    OUT_OF_TOLERANCE = "Webhook timestamp is outside the allowed tolerance."
+    MISSING_SECRET = "Missing webhook secret."
+    INVALID_SECRET = "The webhook secret is not valid (expected whsec_ followed by base64)."
+    NO_MATCH = "No webhook signature matched."
+    INVALID_BODY = "The webhook body is not JSON."
+    TIMESTAMP = /\A[0-9]{1,12}\z/
+    BASE64 = %r{\A[A-Za-z0-9+/]*={0,2}\z}
+    private_constant :MISSING_HEADERS, :INVALID_TIMESTAMP, :OUT_OF_TOLERANCE, :MISSING_SECRET, :INVALID_SECRET,
+                     :NO_MATCH, :INVALID_BODY, :TIMESTAMP, :BASE64
+
+    module_function
+
+    # Verifies a delivery and returns the WebhookEvent. Raises WebhookVerificationError otherwise.
+    #
+    # - +payload+: the raw request body exactly as received (before any JSON parsing), as a String.
+    # - +headers+: the request headers, any Hash-like object (names in any case; a Rack env with +HTTP_WEBHOOK_ID+
+    #   style keys works too). Several values for one header are joined with a space.
+    # - +secret+: the endpoint's signing secret (+whsec_…+).
+    # - +tolerance+: seconds the timestamp may differ from now (default 300; nil means the default). +now+: injectable (Integer or Time).
+    #
+    # Deduplicate on the +webhook-id+ header (retries reuse it) and answer 2xx quickly.
+    def verify(payload, headers, secret, tolerance: DEFAULT_WEBHOOK_TOLERANCE, now: nil)
+      msg_id = header(headers, "webhook-id")
+      timestamp = header(headers, "webhook-timestamp")
+      signatures = header(headers, "webhook-signature")
+      fail!(MISSING_HEADERS) if [msg_id, timestamp, signatures].any? { |v| v.nil? || v.empty? }
+      fail!(INVALID_TIMESTAMP) unless TIMESTAMP.match?(timestamp)
+      tolerance = DEFAULT_WEBHOOK_TOLERANCE if tolerance.nil?
+      current = now.nil? ? Time.now.to_i : now.to_i
+      fail!(OUT_OF_TOLERANCE) if (current - Integer(timestamp, 10)).abs > tolerance
+
+      body = bytes(payload)
+      expected = OpenSSL::HMAC.digest("SHA256", secret_key(secret), "#{msg_id}.#{timestamp}.".b + body)
+      signatures.split(/ /).each do |entry|
+        version, signature = entry.split(",", 2)
+        next unless version == "v1" && signature && !signature.empty?
+
+        given = decode64(signature)
+        next if given.nil? || given.bytesize != expected.bytesize
+        next unless OpenSSL.fixed_length_secure_compare(given, expected)
+
+        return parse_event(body)
+      end
+      fail!(NO_MATCH)
+    end
+
+    # The +webhook-signature+ value (+"v1,<base64>"+) for a payload: useful to test your endpoint locally.
+    def sign(msg_id, timestamp, payload, secret)
+      digest = OpenSSL::HMAC.digest("SHA256", secret_key(secret), "#{msg_id}.#{Integer(timestamp)}.".b + bytes(payload))
+      "v1,#{[digest].pack("m0")}"
+    end
+
+    def header(headers, name)
+      return nil unless headers.respond_to?(:each)
+
+      rack_name = "HTTP_#{name.upcase.tr("-", "_")}"
+      values = []
+      headers.each do |key, value|
+        key = key.to_s
+        next unless key.casecmp?(name) || key == rack_name
+
+        Array(value).each { |v| values << v.to_s }
+      end
+      values.empty? ? nil : values.join(" ")
+    end
+
+    def secret_key(secret)
+      fail!(MISSING_SECRET) if !secret.is_a?(String) || secret.empty?
+      raw = secret.delete_prefix("whsec_")
+      key = decode64(raw)
+      fail!(INVALID_SECRET) if key.nil? || key.empty?
+      key
+    end
+
+    def decode64(text)
+      return nil unless BASE64.match?(text) && (text.length % 4).zero?
+
+      text.unpack1("m0")
+    rescue ArgumentError
+      nil
+    end
+
+    def bytes(payload)
+      raise ArgumentError, "payload must be the raw body as a String" unless payload.respond_to?(:to_str)
+
+      payload.to_str.b
+    end
+
+    def parse_event(body)
+      parsed = JSON.parse(body.dup.force_encoding(Encoding::UTF_8))
+      fail!(INVALID_BODY) unless parsed.is_a?(Hash)
+      WebhookEvent.from_h(parsed)
+    rescue JSON::ParserError, EncodingError
+      fail!(INVALID_BODY)
+    end
+
+    def fail!(message)
+      raise WebhookVerificationError, message
+    end
+
+    private_class_method :header, :secret_key, :decode64, :bytes, :parse_event, :fail!
+  end
+
+  module_function
+
+  # Verifies a webhook delivery; see Webhooks.verify.
+  def verify_webhook(payload, headers, secret, tolerance: DEFAULT_WEBHOOK_TOLERANCE, now: nil)
+    Webhooks.verify(payload, headers, secret, tolerance: tolerance, now: now)
+  end
+
+  # Signs a payload like the service does; see Webhooks.sign.
+  def sign_webhook(msg_id, timestamp, payload, secret)
+    Webhooks.sign(msg_id, timestamp, payload, secret)
+  end
+end

data/lib/email_validation_sdk.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Official Ruby client for the email-validation.org REST API.
+#
+#   require "email_validation_sdk"
+#
+#   client = EmailValidation::Client.new(api_key: ENV.fetch("EV_API_KEY"))
+#   result = client.validate("accepted@sandbox.email-validation.org")
+#   puts result.status # => valid
+#
+# Documentation: https://email-validation.org/docs/sdks/ruby/
+module EmailValidation
+end
+
+require_relative "email_validation_sdk/version"
+require_relative "email_validation_sdk/constants"
+require_relative "email_validation_sdk/errors"
+require_relative "email_validation_sdk/models"
+require_relative "email_validation_sdk/transport"
+require_relative "email_validation_sdk/client"
+require_relative "email_validation_sdk/bulk"
+require_relative "email_validation_sdk/webhooks"

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: email-validation-sdk
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- email-validation.org
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Validate addresses, read credits and usage, run bulk jobs and verify
+  webhook signatures with the email-validation.org REST API. No runtime dependencies.
+email:
+- support@email-validation.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/email_validation_sdk.rb
+- lib/email_validation_sdk/bulk.rb
+- lib/email_validation_sdk/client.rb
+- lib/email_validation_sdk/constants.rb
+- lib/email_validation_sdk/errors.rb
+- lib/email_validation_sdk/models.rb
+- lib/email_validation_sdk/transport.rb
+- lib/email_validation_sdk/version.rb
+- lib/email_validation_sdk/webhooks.rb
+homepage: https://email-validation.org/docs/sdks/ruby/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://email-validation.org/docs/sdks/ruby/
+  documentation_uri: https://email-validation.org/docs/
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.23
+specification_version: 4
+summary: Official Ruby client for the email-validation.org email validation API.
+test_files: []