neverbounce-api 1.0.0

data/lib/never_bounce/api/response/jobs_results.rb

@@ -0,0 +1,34 @@
+
+require_relative "success_message"
+
+module NeverBounce; module API; module Response
+  class JobsResults < SuccessMessage
+    require_relative "jobs_results/item"
+    require_relative "jobs_results/query"
+
+    # @!attribute items
+    #   @return [Array<Item>]
+    oattr :items, :writer
+
+    # @!attribute query
+    #   @return [Query]
+    oattr :query, :writer
+
+    # @!attribute total_pages
+    #   @return [Integer]
+    oattr :total_pages, :scalar, type: :integer
+
+    # @!attribute total_results
+    #   @return [Integer]
+    oattr :total_results, :scalar, type: :integer
+
+    def items
+      # NOTE: I take courage to rename original response key since having class `Results::Result` is total ugliness.
+      @items ||= body_hash.fetch("results").map { |h| Item.new(body_hash: h) }
+    end
+
+    def query
+      @query ||= Query.new(body_hash: body_hash.fetch("query"))
+    end
+  end
+end; end; end

data/lib/never_bounce/api/response/jobs_results/item.rb

@@ -0,0 +1,65 @@
+
+require "never_bounce/api/response/address_info"
+require "never_bounce/api/response/container"
+
+require_relative "../jobs_results"
+
+module NeverBounce; module API; module Response; class JobsResults
+  class Item < Container
+    # @!attribute address_info
+    #   @return [AddressInfo]
+    oattr :address_info, :writer
+
+    # @!attribute data
+    #   @return [Hash]
+    oattr :data, :writer
+
+    # @!attribute email
+    #   @return [String]
+    oattr :email, :writer
+
+    # @!attribute flags
+    #   @return [Array<String>]
+    oattr :flags, :writer
+
+    # @!attribute result
+    #   @return [String]
+    oattr :result, :writer
+
+    # @!attribute suggested_correction
+    #   @return [String]
+    oattr :suggested_correction, :writer
+
+    def address_info
+      @address_info = AddressInfo.new(body_hash: body_hash.fetch("verification").fetch("address_info"))
+    end
+
+    def email
+      @email ||= data["email"]
+    end
+
+    def flags
+      @flags ||= body_hash.fetch("verification").fetch("flags")
+    end
+
+    def data
+      @data ||= body_hash.fetch("data")
+    end
+
+    def result
+      @result ||= body_hash.fetch("verification").fetch("result")
+    end
+
+    def suggested_correction
+      @suggested_correction ||= body_hash.fetch("verification").fetch("suggested_correction")
+    end
+  end
+end; end; end; end
+
+#
+# Implementation notes:
+#
+# * I use a more streamlined structure here, not reflecting API JSON reply structure.
+#   I skip `verification` key entirely, since it has zero value to client code.
+# * According to API spec, `data` has varying keys based on originally uploaded CSV.
+# * We extract some important keys like `email` from `data`. `data` stays intact.

data/lib/never_bounce/api/response/jobs_results/query.rb

@@ -0,0 +1,20 @@
+
+require "never_bounce/api/response/container"
+
+require_relative "../jobs_results"
+
+module NeverBounce; module API; module Response; class JobsResults
+  class Query < Container
+    # @!attribute items_per_page
+    #   @return [Integer]
+    oattr :items_per_page, :scalar, type: :integer
+
+    # @!attribute job_id
+    #   @return [Integer]
+    oattr :job_id, :scalar, type: :integer
+
+    # @!attribute page
+    #   @return [Integer]
+    oattr :page, :scalar, type: :integer
+  end
+end; end; end; end

data/lib/never_bounce/api/response/jobs_search.rb

@@ -0,0 +1,33 @@
+
+require_relative "success_message"
+
+module NeverBounce; module API; module Response
+  class JobsSearch < SuccessMessage
+    require_relative "jobs_search/result"
+    require_relative "jobs_search/query"
+
+    # @!attribute query
+    #   @return [Query]
+    oattr :query, :writer
+
+    # @!attribute results
+    #   @return [Array<Result>]
+    oattr :results, :writer
+
+    # @!attribute total_pages
+    #   @return [Integer]
+    oattr :total_pages, :scalar, type: :integer
+
+    # @!attribute total_results
+    #   @return [Integer]
+    oattr :total_results, :scalar, type: :integer
+
+    def query
+      @query ||= Query.new(body_hash: body_hash.fetch("query"))
+    end
+
+    def results
+      @results ||= body_hash.fetch("results").map { |h| Result.new(body_hash: h) }
+    end
+  end
+end; end; end

data/lib/never_bounce/api/response/jobs_search/query.rb

@@ -0,0 +1,16 @@
+
+require "never_bounce/api/response/container"
+
+require_relative "../jobs_search"
+
+module NeverBounce; module API; module Response; class JobsSearch
+  class Query < Container
+    # @!attribute items_per_page
+    #   @return [Integer]
+    oattr :items_per_page, :scalar, type: :integer
+
+    # @!attribute page
+    #   @return [Integer]
+    oattr :page, :scalar, type: :integer
+  end
+end; end; end; end

data/lib/never_bounce/api/response/jobs_search/result.rb

@@ -0,0 +1,13 @@
+
+require "never_bounce/api/response/container"
+require "never_bounce/api/response/feature/job_status_fields"
+
+require_relative "../jobs_search"
+
+module NeverBounce; module API; module Response; class JobsSearch
+  # Bulk job status.
+  # @see Response::Feature::JobStatusFields
+  class Result < Container
+    Response::Feature::JobStatusFields.load(self)
+  end
+end; end; end; end

data/lib/never_bounce/api/response/jobs_start.rb

@@ -0,0 +1,10 @@
+
+require_relative "success_message"
+
+module NeverBounce; module API; module Response
+  class JobsStart < SuccessMessage
+    # @!attribute queue_id
+    #   @return [String]
+    oattr :queue_id, :scalar
+  end
+end; end; end

data/lib/never_bounce/api/response/jobs_status.rb

@@ -0,0 +1,11 @@
+
+require "never_bounce/api/response/feature/job_status_fields"
+
+require_relative "success_message"
+
+module NeverBounce; module API; module Response
+  # @see Feature::JobStatusFields
+  class JobsStatus < SuccessMessage
+    Response::Feature::JobStatusFields.load(self)
+  end
+end; end; end

data/lib/never_bounce/api/response/message.rb

@@ -0,0 +1,32 @@
+
+require_relative "container"
+
+module NeverBounce; module API; module Response
+  # A response message from the server.
+  # A top-level container with a few extra features.
+  class Message < Container
+    # <tt>true</tt> if this an error message.
+    # @see #success?
+    def error?
+      !success?
+    end
+
+    # An alias to {#success?}.
+    def ok?
+      success?
+    end
+
+    # <tt>true</tt> if this is a success message.
+    # @abstract
+    def success?
+      raise NotImplementedError, "Redefine `success?` in your class: #{self.class}"
+    end
+  end
+end; end; end
+
+#
+# Implementation notes:
+#
+# * `ErrorMessage` and `SuccessMessage` are ancestors of this class.
+#   I don't go for more correct `Message::Error` since I want to keep this sub-hierarchy flat.
+#   There aren't going to be a big family of `*Message`, so simplified suffix grouping should be okay.

data/lib/never_bounce/api/response/single_check.rb

@@ -0,0 +1,68 @@
+
+require "never_bounce/api/response/address_info"
+require "never_bounce/api/response/credits_info/monthly"
+require "never_bounce/api/response/credits_info/paid"
+
+require_relative "success_message"
+
+module NeverBounce; module API; module Response;
+  class SingleCheck < SuccessMessage
+    # @!attribute flags
+    #   @return [String]
+    oattr :flags, :scalar
+
+    # @!attribute result
+    #   @return [String]
+    oattr :result, :scalar
+
+    # @!attribute suggested_correction
+    #   @return [String]
+    oattr :suggested_correction, :scalar
+
+    # @!attribute address_info
+    #   @return [AddressInfo]
+    #   @return [nil]
+    oattr :address_info, :writer
+
+    # @!attribute credits_info
+    #   @return [CreditsInfo::Monthly]
+    #   @return [CreditsInfo::Paid]
+    #   @return [nil]
+    oattr :credits_info, :writer
+
+    def address_info
+      igetset(:address_info) do
+        if body_hash.has_key?(k = "address_info")
+          Response::AddressInfo.new(body_hash: body_hash.fetch(k))
+        end
+      end
+    end
+
+    # <tt>true</tt> if {#address_info} is present.
+    def address_info?
+      !address_info.nil?
+    end
+
+    def credits_info
+      igetset(:credits_info) do
+        if (body_hash.has_key?(k = "credits_info"))
+          h = body_hash.fetch(k)
+          klass = if h.has_key? "monthly_api_usage"
+            CreditsInfo::Monthly
+          elsif h.has_key? "paid_credits_remaining"
+            CreditsInfo::Paid
+          else
+            raise "Unknown `credits_info`: #{h.inspect}"
+          end
+
+          klass.new(h)
+        end
+      end
+    end
+
+    # <tt>true</tt> if {#credits_info} is present.
+    def credits_info?
+      !credits_info.nil?
+    end
+  end
+end; end; end

data/lib/never_bounce/api/response/status_message.rb

@@ -0,0 +1,17 @@
+
+require_relative "message"
+
+module NeverBounce; module API; module Response
+  # A message having <tt>status</tt> and <tt>execution_time</tt>.
+  class StatusMessage < Message
+    # @!attribute execution_time
+    #   Request execution time in milliseconds.
+    #   @return [Integer]
+    oattr :execution_time, :scalar, type: :integer
+
+    # @!attribute status
+    #   Status mnemo as returned by the server.
+    #   @return [String]
+    oattr :status, :scalar
+  end
+end; end; end

data/lib/never_bounce/api/response/success_message.rb

@@ -0,0 +1,12 @@
+
+require_relative "status_message"
+
+module NeverBounce; module API; module Response
+  # A meaningful (success) response from the server.
+  class SuccessMessage < StatusMessage
+    # @return [true]
+    def success?
+      true
+    end
+  end
+end; end; end

data/lib/never_bounce/api/session.rb

@@ -0,0 +1,141 @@
+
+require "httparty"
+
+require "never_bounce/api/feature/basic_initialize"
+require "never_bounce/api/feature/igetset"
+require "never_bounce/api/feature/require_attr"
+
+module NeverBounce; module API
+  # A single request-response session (server dialog).
+  # @see API::Feature::BasicInitialize
+  # @see API::Feature::Igetset
+  # @see API::Feature::RequireAttr
+  class Session
+    API::Feature::BasicInitialize.load(self)
+    API::Feature::Igetset.load(self)
+    API::Feature::RequireAttr.load(self)
+
+    attr_writer :httparty, :response, :robj_hash_preview, :robj_klass_and_attrs, :server_content_type, :server_obj, :server_ok, :server_raw
+
+    # An instance of <tt>Request::Base</tt> successor.
+    # @return [Object]
+    attr_accessor :request
+
+    # HTTParty module. Default is <tt>HTTParty</tt>.
+    # @!attribute httparty
+    # @return [Module]
+    def httparty
+      @httparty ||= HTTParty
+    end
+
+    # Meaningful response object.
+    # @!attribute response
+    # @return [Response::Message]
+    # @return [Response::ErrorMessage]
+    def response
+      @response ||= begin
+        klass, attrs = require_attr(:robj_klass_and_attrs)
+        klass.new(attrs)
+      end
+    end
+
+    # Render response object class and constructor attributes based on peeking in the data.
+    # @!attribute robj_klass_and_attrs
+    # @return [Array<Class,Hash>]
+    def robj_klass_and_attrs
+      @robj_klass_and_attrs ||= begin
+        if (h = robj_hash_preview).is_a? Hash
+          # Determine response class based on API convention.
+          begin
+            [
+              h.fetch("status") == "success" ? request.class.response_klass : Response::ErrorMessage,
+              body_hash: robj_hash_preview,
+            ]
+          rescue KeyError
+            raise FormatError, "Key 'status' not found: #{h.inspect}"
+          end
+        elsif robj_hash_preview == false
+          # Let response class handle it on its own.
+          [
+            request.class.response_klass,
+            raw: server_raw,
+          ]
+        else
+          raise AttributeError, "Unknown `robj_hash_preview`: #{robj_hash_preview.inspect}"
+        end
+      end
+    end
+
+    # Response body, opportunistically JSON-parsed based on <tt>server_content_type</tt>.
+    # @return [Hash]
+    # @return [false] If <tt>server_content_type</tt> isn't a JSON.
+    def robj_hash_preview
+      igetset(:robj_hash_preview) do
+        case require_attr(:server_content_type)
+        when "application/json"
+          begin
+            JSON.parse(server_raw)
+          rescue JSON::ParserError => e
+            raise FormatError, "#{e.class}: #{e.message}"
+          end
+        else
+          false
+        end
+      end
+    end
+
+    # Server response code. Default is <tt>server_obj.code</tt>.
+    # @!attribute server_code
+    # @return [Integer]
+    def server_code
+      @server_code ||= require_attr(:server_obj).code
+    end
+
+    # Server response content type. Default is <tt>server_obj.content_type</tt>.
+    # @!attribute server_content_type
+    # @return [String]
+    def server_content_type
+      @server_content_type ||= begin
+        require_attr(:server_obj).content_type
+      end
+    end
+
+    # Make a request, return server response object from HTTParty.
+    # @return [Object] An <tt>HTTParty::Response</tt>.
+    def server_obj
+      @server_obj ||= begin
+        httparty.send(*require_attr(:request).to_httparty)
+      end
+    end
+
+    # <tt>true</tt> if response is an OK response.
+    # @!attribute server_ok
+    # @return [Boolean]
+    def server_ok
+      igetset(:server_ok) { require_attr(:server_obj).ok? }
+    end
+
+    alias_method :server_ok?, :server_ok
+
+    # Raw server response body. Default is <tt>server_obj.body</tt>.
+    # @!attribute server_raw
+    # @return [String]
+    def server_raw
+      @server_raw ||= begin
+        raise RequestError, "Code not OK: #{server_code}" if not server_ok?
+        server_obj.body
+      end
+    end
+  end
+end; end
+
+#
+# Implementation notes:
+#
+# * `server_*` methods deal with stage 1, received directly from the server via HTTParty.
+#   `robj_*` methods deal with stage 2, converting raw data into response object.
+#   Everything `response*` relates to meaningful response object.
+# * Response classes can natively parse their raw content to JSON, and that is right.
+#   BUT we also use JSON parsing here, for the purpose of detecting success/error response class.
+# * We inherit response "OK?" condition from HTTParty, which inherits it from `net/http`.
+#   `ok?` maps to `Net::HTTPOK` class equality check.