neverbounce-api 1.0.0

data/lib/never_bounce/api/error.rb

@@ -0,0 +1,21 @@
+
+module NeverBounce; module API
+  # Base class for all errors.
+  # @abstract
+  class Error < StandardError; end
+
+  # Incorrect attribute usage.
+  class AttributeError < Error; end
+
+  # Data format errors happening in our land.
+  class FormatError < Error; end
+
+  # Something went wrong with the request.
+  class RequestError < Error; end
+end; end
+
+#
+# Implementation notes:
+#
+# * None of these exceptions should be suppressed in end-user script.
+#   Either they must be handled or they should crash the end-user script with a full backtrace.

data/lib/never_bounce/api/feature/basic_initialize.rb

@@ -0,0 +1,20 @@
+
+module NeverBounce; module API; module Feature
+  # Provide the basic method <tt>#initialize</tt> to the owner class.
+  # @see InstanceMethods#initialize
+  module BasicInitialize
+    # @param owner [Class]
+    # @return [nil]
+    def self.load(owner)
+      return if owner < InstanceMethods
+      owner.send(:include, InstanceMethods)
+    end
+
+    module InstanceMethods
+      # See source for details.
+      def initialize(attrs = {})
+        attrs.each { |k, v| public_send("#{k}=", v) }
+      end
+    end
+  end
+end; end; end

data/lib/never_bounce/api/feature/eigencache.rb

@@ -0,0 +1,48 @@
+
+module NeverBounce; module API; module Feature
+  # Eigenclass (singleton class)-based cache which allows to handle "hidden" instance variables.
+  # @see InstanceMethods#_cache
+  module Eigencache
+    # @param owner [Class]
+    # @return [nil]
+    def self.load(owner)
+      return if owner < InstanceMethods
+      owner.send(:include, InstanceMethods)
+    end
+
+    module InstanceMethods
+      # Hidden cache.
+      #
+      #   def body
+      #     _cache[:body] ||= File.read("my-bulky-body.csv")
+      #   end
+      #
+      #   def body=(v)
+      #     _cache[:body] = v
+      #   end
+      #
+      # @return [Hash]
+      def _cache
+        if eigen.instance_variable_defined?(k = :@cache)
+          eigen.instance_variable_get(k)
+        else
+          eigen.instance_variable_set(k, {})
+        end
+      end
+
+      #---------------------------------------
+      private
+
+      # Object's eigenclass (singleton class).
+      # @return [Class]
+      def eigen
+        class << self; self; end
+      end
+    end
+  end
+end; end; end
+
+#
+# Implementation notes:
+#
+# * As of Ruby 2.1 `Object#singleton_class` is introduced. We use our own compatible implementation, `eigen`.

data/lib/never_bounce/api/feature/igetset.rb

@@ -0,0 +1,41 @@
+
+module NeverBounce; module API; module Feature
+  # @see InstanceMethods#igetset
+  module Igetset
+    # @param owner [Class]
+    # @return [nil]
+    def self.load(owner)
+      return if owner < InstanceMethods
+      owner.send(:include, InstanceMethods)
+    end
+
+    module InstanceMethods
+      private
+
+      # Get/set an OTF instance variable of any type.
+      #
+      # Ruby's <tt>||=</tt> works nicely with object instances, but requires special bulky treatment for <tt>nil</tt> and <tt>false</tt>.
+      # For example, this will cause a hidden glitch since <tt>==</tt> can evaluate to <tt>false</tt>:
+      #
+      #   @is_verbose ||= begin
+      #     # This clause will be evaluated *every time* if its value is `false`.
+      #     ENV["VERBOSE"] == "y"
+      #   end
+      #
+      # There's a number of solutions to this problem, all of which involve calling <tt>instance_variable_*</tt> a few times per attribute accessor.
+      #
+      # <tt>igetset</tt> does this job for you. All you have to do is specify a block to compute the value.
+      #
+      #   igetset(:is_verbose) { ENV["VERBOSE"] == "y" }
+      #
+      # See source for details.
+      def igetset(name, &compute)
+        if instance_variable_defined?(k = "@#{name}")
+          instance_variable_get(k)
+        else
+          instance_variable_set(k, compute.call)
+        end
+      end
+    end
+  end
+end; end; end

data/lib/never_bounce/api/feature/oattrs.rb

@@ -0,0 +1,100 @@
+
+module NeverBounce; module API; module Feature
+  # Declare and manage on-the-fly (OTF) attributes of the class, codenamed "oattrs".
+  # @see ClassMethods#oattr
+  # @see ClassMethods#oattrs
+  # @see InstanceMethods#touch
+  module Oattrs
+    # @return [nil]
+    def self.load(owner)
+      return if owner < InstanceMethods
+      owner.extend(ClassMethods)
+      owner.send(:include, InstanceMethods)
+    end
+
+    module ClassMethods
+      # Return oattrs declared so far, recurse all superclasses.
+      #
+      #   oattrs    # => [:first_name, :last_name]
+      #
+      # @!attribute oattrs
+      # @return [Array]
+      def oattrs
+        @attrs ||= if superclass.respond_to?(m = :oattrs)
+          superclass.send(m).dup
+        else
+          []
+        end
+      end
+
+      def oattrs=(ar)
+        @oattrs = ar
+      end
+
+      # Declare an OTF attribute.
+      #
+      #   class Klass
+      #     oattr :first_name, :writer
+      #     oattr :goods, :custom
+      #
+      #     def first_name
+      #       @first_name ||= ENV["FIRST_NAME"]
+      #     end
+      #
+      #     def goods
+      #       @goods ||= ...
+      #
+      #     def goods=(ar)
+      #       @goods = ar
+      #     ...
+      #
+      # @return [Symbol] <tt>name</tt>.
+      # @see InstanceMethods#touch
+      def oattr(name, type)
+        case type
+        when :custom
+          # Do nothing, just register attr below.
+        when :writer
+          attr_writer name
+        else
+          raise ArgumentError, "Unknown type: #{type.inspect}"
+        end
+
+        # Register and return.
+        name.tap { oattrs << name}
+      end
+    end
+
+    module InstanceMethods
+      # Load all oattrs by "touching" them.
+      #
+      #   irb> resp = client.jobs_delete(job_id: 353701)
+      #   => #<NeverBounce::API::Response::ErrorMessage:0x0056245978aec8>
+      #   irb> resp.touch
+      #   => #<NeverBounce::API::Response::ErrorMessage:0x0056245978aec8 @message="Invalid job ID 353701", @execution_time=15, @status="general_failure">
+      #
+      # @return [self]
+      def touch
+        self.class.oattrs.each do |name|
+          v = public_send(name)
+
+          # Touch recursively. Support simple collections.
+          if v.respond_to? :touch
+            v.touch
+          elsif v.is_a? Array
+            v.each { |r| r.touch if r.respond_to? :touch }
+          end
+        end
+
+        self
+      end
+    end
+  end
+end; end; end
+
+#
+# Implementation notes:
+#
+# * Originally I've used `attr` and `attrs` as method names.
+#   Sadly enough, YARD choked on `attr ...` with no reasonable way to work around it and tell it to ignore these statements.
+#   That led me to the conclusion that `attr` acts more like a language construct, so I'd rather not override it, but make my own.

data/lib/never_bounce/api/feature/require_attr.rb

@@ -0,0 +1,27 @@
+
+require "never_bounce/api/error"
+
+module NeverBounce; module API; module Feature
+  # Provide attribute validation method(s) to the owner class.
+  # @see InstanceMethods#initialize
+  module RequireAttr
+    # @param owner [Class]
+    # @return [nil]
+    def self.load(owner)
+      return if owner < InstanceMethods
+      owner.send(:include, InstanceMethods)
+    end
+
+    module InstanceMethods
+      private
+
+      # Require attribute to be set. Return attribute value.
+      # @return [mixed]
+      def require_attr(name)
+        send(name).tap do |_|
+          raise AttributeError, "Attribute must be set: #{name}" if _.nil?
+        end
+      end
+    end
+  end
+end; end; end

data/lib/never_bounce/api/request/account_info.rb

@@ -0,0 +1,29 @@
+
+require "never_bounce/api/response/account_info"
+
+require_relative "base"
+
+module NeverBounce; module API; module Request
+  class AccountInfo < Base
+    # @return [Symbol]
+    def self.http_method
+      :get
+    end
+
+    # @return [String]
+    def self.path
+      "account/info"
+    end
+
+    # @return [Response::AccountInfo]
+    def self.response_klass
+      Response::AccountInfo
+    end
+
+    def to_h
+      {
+        key: require_attr(:api_key),
+      }
+    end
+  end
+end; end; end

data/lib/never_bounce/api/request/base.rb

@@ -0,0 +1,102 @@
+
+require "never_bounce/api/feature/basic_initialize"
+require "never_bounce/api/feature/require_attr"
+
+module NeverBounce; module API; module Request
+  # @abstract
+  # @see API::Feature::BasicInitialize
+  class Base
+    API::Feature::BasicInitialize.load(self)
+    API::Feature::RequireAttr.load(self)
+
+    # User's API key.
+    # @return [String]
+    attr_accessor :api_key
+    attr_writer :api_url, :headers, :user_agent
+
+    # Custom API URL. Default is <tt>https://api.neverbounce.com/v4</tt>.
+    # @return [String]
+    def api_url
+      @api_url ||= "https://api.neverbounce.com/v4"
+    end
+
+    # @!attribute headers
+    # @return [Array]
+    def headers
+      {
+        "Content-Type" => "application/json",
+        "User-Agent" => user_agent,
+      }
+    end
+
+    # <tt>:get</tt>, <tt>:post</tt> or whatever.
+    # @abstract
+    # @return [Symbol]
+    # @return [String]
+    def self.http_method
+      raise NotImplementedError, "Redefine `self.http_method` in your class: #{self}"
+    end
+
+    # Request path on server, e.g. <tt>"jobs/parse"</tt>.
+    # @abstract
+    # @return [String]
+    def self.path
+      raise NotImplementedError, "Redefine `self.path` in your class: #{self}"
+    end
+
+    # @abstract
+    # @return [Class]
+    def self.response_klass
+      raise NotImplementedError, "Redefine `self.response_klass` in your class: #{self}"
+    end
+
+    # Build arguments for cURL OS command.
+    # @return [Array]
+    def to_curl
+      # NOTE: I consider we should use long options to avoid ambiguity of ones like `-u` etc.
+      @curl ||= begin
+        ar = [
+          "--request", self.class.http_method.to_s.upcase,
+          "--url", "#{api_url}/#{self.class.path}",
+        ]
+
+        ar += headers.reject { |k,| k == "User-Agent" }.flat_map do |k, v|
+          ["--header", "#{k}: #{v}"]
+        end
+
+        ar += ["--data-binary", to_h.to_json]
+
+        ar
+      end
+    end
+
+    # Build a <tt>Hash</tt> representation of request data.
+    # @abstract
+    # @return [Hash]
+    def to_h
+      raise NotImplementedError, "Redefine `to_h` in your class: #{self.class}"
+    end
+
+    # Build argumentsfor <tt>Httparty</tt> invocation.
+    # @return [Array]
+    def to_httparty
+      [
+        self.class.http_method,   # E.g. `:get`.
+        "#{api_url}/#{self.class.path}",
+        {
+          body: to_h.to_json,
+          headers: headers,
+        }
+      ]
+    end
+
+    # @!attribute user_agent
+    # @return [String]
+    def user_agent
+      @user_agent ||= [
+        "NeverBounceApi-Ruby/#{API::VERSION} (#{RUBY_PLATFORM})",
+        "Ruby/#{RUBY_VERSION} (p #{RUBY_PATCHLEVEL}; rev #{RUBY_REVISION})",
+      ].join(" ")
+    end
+  end
+end; end; end

data/lib/never_bounce/api/request/jobs_create.rb

@@ -0,0 +1,90 @@
+
+require_relative "base"
+
+module NeverBounce; module API; module Request
+  class JobsCreate < Base
+    # @return [Boolean]
+    attr_accessor :auto_parse
+
+    # @return [Boolean]
+    attr_accessor :auto_start
+
+    # @return [String]
+    attr_accessor :filename
+
+    # Input specification.
+    # @return [String] URL if <tt>input_location</tt> is <tt>"remote".
+    # @return [Array<Array<email, name>>] Structure if <tt>input_location</tt> is "supplied".
+    attr_accessor :input
+
+    # @return [String]
+    attr_accessor :input_location
+
+    # @return [Boolean]
+    attr_accessor :run_sample
+
+    # @return [Symbol]
+    def self.http_method
+      :post
+    end
+
+    # @return [String]
+    def self.path
+      "jobs/create"
+    end
+
+    # @return [Response::JobsCreate]
+    def self.response_klass
+      Response::JobsCreate
+    end
+
+    # Return a ready-to-merge mode attributes hash.
+    # @return [Hash]
+    def mode_h
+      @mode_h ||= {}.tap do |_|
+        unless (v = auto_start).nil?
+          _[:auto_start] = v
+        end
+
+        unless (v = auto_parse).nil?
+          _[:auto_parse] = v
+        end
+
+        unless (v = run_sample).nil?
+          _[:run_sample] = v
+        end
+      end
+    end
+
+    # @return [Hash]
+    def to_h
+      input = require_attr(:input)
+      input_location = require_attr(:input_location)
+
+      # Validate `input_location` and `input`.
+
+      if not ["remote_url", "supplied"].include? input_location
+        raise AttributeError, "Unknown `input_location`: #{input_location.inspect}"
+      end
+
+      if input_location == "supplied"
+        raise AttributeError, "Invalid `input` for `input_location` == #{input_location.inspect}: #{input.inspect}" if not input.is_a? Array
+
+        # Skim through elements of `input`, raise if invalid structure detected, with details.
+        input.each do |elem|
+          em = [AttributeError, "Invalid `input` element: #{elem.inspect}"]
+          raise(*em) unless elem.is_a? Array
+          raise(*em) unless elem.map(&:class) == [String, String]
+        end
+      end
+
+      # Result.
+      {
+        input: input,
+        input_location: input_location,
+        filename: require_attr(:filename),
+        key: require_attr(:api_key),
+      }.merge(mode_h)
+    end
+  end
+end; end; end