neverbounce-api 1.0.0

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

@@ -0,0 +1,43 @@
+
+require_relative "container"
+
+module NeverBounce; module API; module Response
+  # Generic address info used in a number of responses.
+  class AddressInfo < Container
+    # @!attribute addr
+    #   @return [String]
+    oattr :addr, :scalar
+
+    # @!attribute alias
+    #   @return [String]
+    oattr :alias, :scalar
+
+    # @!attribute domain
+    #   @return [String]
+    oattr :domain, :scalar
+
+    # @!attribute fqdn
+    #   @return [String]
+    oattr :fqdn, :scalar
+
+    # @!attribute host
+    #   @return [String]
+    oattr :host, :scalar
+
+    # @!attribute normalized_email
+    #   @return [String]
+    oattr :normalized_email, :scalar
+
+    # @!attribute original_email
+    #   @return [String]
+    oattr :original_email, :scalar
+
+    # @!attribute subdomain
+    #   @return [String]
+    oattr :subdomain, :scalar
+
+    # @!attribute tld
+    #   @return [String]
+    oattr :tld, :scalar
+  end
+end; end; end

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

@@ -0,0 +1,15 @@
+
+require "never_bounce/api/feature/basic_initialize"
+require "never_bounce/api/feature/igetset"
+require "never_bounce/api/feature/require_attr"
+
+module NeverBounce; module API; module Response
+  # @see API::Feature::BasicInitialize
+  # @see API::Feature::Igetset
+  # @see API::Feature::RequireAttr
+  class Base
+    API::Feature::BasicInitialize.load(self)
+    API::Feature::Igetset.load(self)
+    API::Feature::RequireAttr.load(self)
+  end
+end; end; end

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

@@ -0,0 +1,126 @@
+
+require "json"
+
+require "never_bounce/api/feature/eigencache"
+require "never_bounce/api/feature/oattrs"
+require "never_bounce/api/feature/require_attr"
+
+require_relative "base"
+
+module NeverBounce; module API; module Response
+  # A container with values, by default supports JSON parsing.
+  # @see API::Feature::Eigencache
+  # @see API::Feature::Oattrs
+  # @see API::Feature::RequireAttr
+  class Container < Base
+    API::Feature::Eigencache.load(self)
+    API::Feature::Oattrs.load(self)
+    API::Feature::RequireAttr.load(self)
+
+    # Container data. Default is JSON-parsed {#raw}.
+    # @!attribute body_hash
+    # @return [Hash]
+    def body_hash
+      _cache[:body_hash] ||= JSON.parse(require_attr(:raw))
+    end
+
+    def body_hash=(value)
+      _cache[:body_hash] = value
+    end
+
+    # Raw response body.
+    # @!attribute raw
+    # @return [String]
+    def raw
+      _cache[:raw]
+    end
+
+    def raw=(value)
+      _cache[:raw] ||= value
+    end
+
+    #--------------------------------------- Misc
+
+    class << self
+      private
+
+      # Declare & register an oattr.
+      #
+      #   oattr :first_name, :scalar    # => :first_name
+      #   oattr ...                     # Handled by `Feature::Oattrs`.
+      #
+      # @return [Symbol] <tt>name</tt>.
+      # @see Feature::Oattrs::ClassMethods#oattr
+      def oattr(name, type, *args)
+        if type == :scalar
+          scalar_oattr(name, *args)
+          name.tap { oattrs << name }
+        else
+          # Handle other types in parent class.
+          super
+        end
+      end
+
+      # Build a generic scalar oattr.
+      #
+      #   scalar_oattr :first_name
+      #   scalar_oattr :page, type: :integer
+      #   scalar_oattr :total_valid, type: :integer, allow_nil: true
+      #
+      # @return [Symbol]
+      def scalar_oattr(name, options = {})
+        o, options = {}, options.dup
+        o[k = :allow_nil] = options.include?(k) ? options.delete(k) : false
+        o[k = :key] = options.delete(k) || name
+        o[k = :type] = options.delete(k) || :any
+        raise ArgumentError, "Unknown options: #{options.inspect}" if not options.empty?
+
+        code = []
+        code << %{attr_writer :#{name}}
+
+        code << case o[:type]
+          when :any
+            %{def #{name}; @#{name} ||= body_hash.fetch("#{o[:key]}"); end}
+          when :float
+            if o[:allow_nil]
+              %{
+                def #{name}
+                  @#{name} ||= unless (v = body_hash.fetch("#{o[:key]}")).nil?
+                    Float(v)
+                  end
+                end
+              }
+            else
+              %{def #{name}; @#{name} ||= Float(body_hash.fetch("#{o[:key]}")); end}
+            end
+          when :integer
+            if o[:allow_nil]
+              %{
+                def #{name}
+                  @#{name} ||= unless (v = body_hash.fetch("#{o[:key]}")).nil?
+                    Integer(v)
+                  end
+                end
+              }
+            else
+              %{def #{name}; @#{name} ||= Integer(body_hash.fetch("#{o[:key]}")); end}
+            end
+          else
+            raise ArgumentError, "Unknown type: #{o[:type].inspect}"
+          end
+
+        class_eval code.join(";")
+
+        name
+      end
+    end # class << self
+  end
+end; end; end
+
+#
+# Implementation notes:
+#
+# * I go for `class_eval` rather than `define_method` in order to use Ruby's `||=`.
+#   Going without it would require a bunch of `instance_variable_*` calls per each attribute access.
+# * The container performs its own value validation according to attribute definitions.
+#   Thus, when creating a sub-container, it's more correct to pass `body` or `body_hash` to let this validation happen in the sub-container class.

data/lib/never_bounce/api/response/credits_info/base.rb

@@ -0,0 +1,30 @@
+
+require_relative "../container"
+
+module NeverBounce; module API; module Response; module CreditsInfo
+  class Base < Container
+    # @!attribute free_credits_remaining
+    #   @return [Integer]
+    oattr :free_credits_remaining, :scalar, type: :integer
+
+    # @!attribute free_credits_used
+    #   @return [Integer]
+    oattr :free_credits_used, :scalar, type: :integer
+
+    # <tt>:monthly</tt> or <tt>:paid</tt>.
+    # @return [Symbol]
+    def subscription_type
+      raise NotImplementedError, "Redefine `subscription_type` in final class: #{self.class}"
+    end
+
+    # <tt>true</tt> if monthly subscription.
+    def monthly?
+      subscription_type == :monthly
+    end
+
+    # <tt>true</tt> if paid subscription.
+    def paid?
+      subscription_type == :paid
+    end
+  end
+end; end; end; end

data/lib/never_bounce/api/response/credits_info/monthly.rb

@@ -0,0 +1,16 @@
+
+require_relative "base"
+
+module NeverBounce; module API; module Response; module CreditsInfo
+  class Monthly < Base
+    # @!attribute monthly_api_usage
+    #   @return [Integer]
+    oattr :monthly_api_usage, :scalar, type: :integer
+
+    # Always <tt>:monthly</tt>.
+    # @return [Symbol]
+    def subscription_type
+      :monthly
+    end
+  end
+end; end; end; end

data/lib/never_bounce/api/response/credits_info/paid.rb

@@ -0,0 +1,20 @@
+
+require_relative "base"
+
+module NeverBounce; module API; module Response; module CreditsInfo
+  class Paid < Base
+    # @!attribute paid_credits_remaining
+    #   @return [Integer]
+    oattr :paid_credits_remaining, :scalar, type: :integer
+
+    # @!attribute paid_credits_used
+    #   @return [Integer]
+    oattr :paid_credits_used, :scalar, type: :integer
+
+    # Always <tt>:paid</tt>.
+    # @return [Symbol]
+    def subscription_type
+      :paid
+    end
+  end
+end; end; end; end

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

@@ -0,0 +1,17 @@
+
+require_relative "status_message"
+
+module NeverBounce; module API; module Response
+  # A failure (error) response from the server.
+  # @see https://developers.neverbounce.com/v4.0/reference#error-handling
+  class ErrorMessage < StatusMessage
+    # @!attribute message
+    #   @return [String]
+    oattr :message, :scalar
+
+    # @return [false]
+    def success?
+      false
+    end
+  end
+end; end; end

data/lib/never_bounce/api/response/feature/job_status_fields.rb

@@ -0,0 +1,68 @@
+
+require "never_bounce/api/response/container"
+
+module NeverBounce; module API; module Response; module Feature
+  # Common traits for message/container of the job status.
+  # @see InstanceMethods
+  module JobStatusFields
+    require_relative "job_status_fields/total"
+
+    # @param owner [Class]
+    # @return [nil]
+    def self.load(owner)
+      # Validate owner, or calls to `oattr` will fail.
+      raise ArgumentError, "Class #{owner} is not an ancestor of Response::Container" if not owner < Response::Container
+
+      return if owner < InstanceMethods
+      owner.send(:include, InstanceMethods)
+
+      owner.class_eval do
+        oattr :id, :scalar, type: :integer
+
+        oattr :job_status, :scalar
+
+        oattr :bounce_estimate, :scalar, type: :float
+        oattr :filename, :scalar
+        oattr :percent_complete, :scalar, type: :integer
+
+        oattr :total, :writer
+
+        oattr :created_at, :scalar
+        oattr :finished_at, :scalar
+        oattr :started_at, :scalar
+      end
+    end
+
+    # @!attribute id
+    #   @return [Integer]
+    # @!attribute job_status
+    #   @return [String]
+    # @!attribute bounce_estimate
+    #   @return [Float]
+    # @!attribute filename
+    #   @return [String]
+    # @!attribute percent_complete
+    #   @return [Integer]
+    # @!attribute total
+    #   @return [Total]
+    # @!attribute created_at
+    #   @return [String]
+    # @!attribute finished_at
+    #   @return [String]
+    # @!attribute started_at
+    #   @return [String]
+    module InstanceMethods
+      def total
+        @total ||= Total.new(body_hash: body_hash.fetch("total"))
+      end
+    end
+  end
+end; end; end; end
+
+#
+# Implementation notes:
+#
+# * (!) No means discovered to tell YARD that class A inherits methods from here.
+#   Thus, we use a regular `@see` in those using this and other features.
+# * YARD can't read `@!attribute` from inside `class_eval`, just ignores the comments.
+# * YARD sorts all attributes alphabetically, we maintain our order, which is logical+alpha.

data/lib/never_bounce/api/response/feature/job_status_fields/total.rb

@@ -0,0 +1,46 @@
+
+require_relative "../job_status_fields"
+
+module NeverBounce; module API; module Response; module Feature; module JobStatusFields
+  class Total < Container
+    # @!attribute bad_syntax
+    #   @return [Integer]
+    oattr :bad_syntax, :scalar, type: :integer, allow_nil: true
+
+    # @!attribute billable
+    #   @return [Integer]
+    oattr :billable, :scalar, type: :integer, allow_nil: true
+
+    # @!attribute catchall
+    #   @return [Integer]
+    oattr :catchall, :scalar, type: :integer, allow_nil: true
+
+    # @!attribute disposable
+    #   @return [Integer]
+    oattr :disposable, :scalar, type: :integer, allow_nil: true
+
+    # @!attribute duplicates
+    #   @return [Integer]
+    oattr :duplicates, :scalar, type: :integer, allow_nil: true
+
+    # @!attribute invalid
+    #   @return [Integer]
+    oattr :invalid, :scalar, type: :integer, allow_nil: true
+
+    # @!attribute processed
+    #   @return [Integer]
+    oattr :processed, :scalar, type: :integer, allow_nil: true
+
+    # @!attribute records
+    #   @return [Integer]
+    oattr :records, :scalar, type: :integer, allow_nil: true
+
+    # @!attribute unknown
+    #   @return [Integer]
+    oattr :unknown, :scalar, type: :integer, allow_nil: true
+
+    # @!attribute valid
+    #   @return [Integer]
+    oattr :valid, :scalar, type: :integer, allow_nil: true
+  end
+end; end; end; end; end

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

@@ -0,0 +1,10 @@
+
+require_relative "success_message"
+
+module NeverBounce; module API; module Response
+  class JobsCreate < SuccessMessage
+    # @!attribute job_id
+    #   @return [Integer]
+    oattr :job_id, :scalar, type: :integer
+  end
+end; end; end

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

@@ -0,0 +1,8 @@
+
+require_relative "success_message"
+
+module NeverBounce; module API; module Response
+  class JobsDelete < SuccessMessage
+    # No own attributes yet.
+  end
+end; end; end

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

@@ -0,0 +1,19 @@
+
+require_relative "message"
+
+module NeverBounce; module API; module Response
+  # A response to <tt>jobs/download</tt>.
+  # Body is an octet-stream, not a JSON structure.
+  # @see https://developers.neverbounce.com/v4.0/reference#jobs-download
+  class JobsDownload < Message
+    # Always <tt>true</tt>.
+    def success?
+      true
+    end
+  end
+end; end; end
+
+#
+# Implementation notes:
+#
+# * This class uses `body` in its literal form. All the rest basically JSON-parse it.

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

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