postcode-anywhere 1.0.1

data/lib/postcode_anywhere/cleanse_plus/client.rb

@@ -0,0 +1,13 @@
+require 'postcode_anywhere/client'
+require 'postcode_anywhere/cleanse_plus/interactive'
+
+module PostcodeAnywhere
+  module CleansePlus
+    class Client < ::PostcodeAnywhere::Client
+      include PostcodeAnywhere::CleansePlus::Interactive
+      def initialize(options = {})
+        super(options)
+      end
+    end
+  end
+end

data/lib/postcode_anywhere/cleanse_plus/interactive.rb

@@ -0,0 +1,24 @@
+require 'postcode_anywhere/utils'
+require 'postcode_anywhere/cleanse_plus/cleansed_address'
+
+module PostcodeAnywhere
+  module CleansePlus
+    module Interactive
+      include ::PostcodeAnywhere::Utils
+
+      API_VERSION = '1.00'
+
+      CLEANSE_ADDRESS_ENDPOINT = "CleansePlus/Interactive/Cleanse/v#{API_VERSION}/json.ws"
+
+      def address_candidates_for(address, options = {})
+        options.merge!('Address' => address)
+        perform_with_objects(
+          :get,
+          CLEANSE_ADDRESS_ENDPOINT,
+          options,
+          PostcodeAnywhere::CleansePlus::CleansedAddress
+        )
+      end
+    end
+  end
+end

data/lib/postcode_anywhere/client.rb

@@ -0,0 +1,86 @@
+require 'faraday'
+require 'faraday/request/multipart'
+require 'json'
+require 'timeout'
+require 'postcode_anywhere/error'
+require 'postcode_anywhere/response/raise_error'
+require 'postcode_anywhere/response/parse_json'
+
+module PostcodeAnywhere
+  class Client
+    attr_accessor(*Configuration::VALID_CONFIG_KEYS)
+
+    def initialize(options = {})
+      merged_options = PostcodeAnywhere.options.merge(options)
+
+      Configuration::VALID_CONFIG_KEYS.each do |key|
+        send("#{key}=", merged_options[key])
+      end
+    end
+
+    # Perform an HTTP GET request
+    def get(path, body_hash = {}, params = {})
+      request(:get, path, params, body_hash)
+    end
+
+    # Perform an HTTP POST request
+    def post(path, body_hash = {}, params = {})
+      request(:post, path, params, body_hash)
+    end
+
+    def connection_options
+      @connection_options ||= {
+        builder: middleware,
+        headers: {
+          accept: "application/#{@format}",
+          content_type: "application/#{@format}",
+          user_agent: user_agent
+        },
+        request: {
+          open_timeout: 10,
+          timeout: 30
+        }
+      }
+    end
+
+    def connection
+      @connection ||= Faraday.new(@endpoint, connection_options)
+    end
+
+    def middleware
+      @middleware ||= Faraday::RackBuilder.new do |faraday|
+        # Checks for files in the payload, otherwise leaves everything untouched
+        faraday.request :multipart
+        # Encodes as "application/x-www-form-urlencoded" if not already encoded
+        faraday.request :url_encoded
+        # Handle error responses
+        faraday.response :postcode_anywhere_raise_error
+        # Parse JSON response bodies
+        faraday.response :postcode_anywhere_parse_json
+        # Set default HTTP adapter
+        faraday.adapter :net_http
+      end
+    end
+
+    private
+
+    def request(method, path, params = {}, body_hash = {})
+      attach_api_key_to params
+      connection.send(method.to_sym, path, params) do |request|
+        request.body = compile_body(body_hash) unless body_hash.empty?
+      end.env
+      rescue Faraday::Error::TimeoutError, Timeout::Error => error
+        raise(PostcodeAnywhere::Error::RequestTimeout.new(error))
+      rescue Faraday::Error::ClientError, JSON::ParserError => error
+        raise(PostcodeAnywhere::Error.new(error))
+    end
+
+    def attach_api_key_to(params)
+      params.merge!('Key' => @api_key) unless params.keys.include? 'Key'
+    end
+
+    def compile_body(body_hash)
+      body_hash.to_json
+    end
+  end
+end

data/lib/postcode_anywhere/configuration.rb

@@ -0,0 +1,47 @@
+module PostcodeAnywhere
+  module Configuration
+    VALID_CONNECTION_KEYS = [
+      :endpoint,
+      :api_key,
+      :method,
+      :user_agent
+    ].freeze
+
+    VALID_OPTIONS_KEYS      = [:format].freeze
+    VALID_CONFIG_KEYS =
+      VALID_CONNECTION_KEYS +
+      VALID_OPTIONS_KEYS
+
+    DEFAULT_METHOD      = :post
+    DEFAULT_USER_AGENT  = "Postcode Anywhere Ruby Gem/#{PostcodeAnywhere::VERSION}"
+
+    DEFAULT_API_KEY       = ''
+
+    DEFAULT_FORMAT          = :json
+
+    DEFAULT_ENDPOINT        = 'http://services.postcodeanywhere.co.uk/'
+
+    attr_accessor(*VALID_CONFIG_KEYS)
+
+    def self.extended(base)
+      base.reset
+    end
+
+    def reset
+      self.api_key          = DEFAULT_API_KEY
+      self.endpoint         = DEFAULT_ENDPOINT
+      self.format           = DEFAULT_FORMAT
+      self.method           = DEFAULT_METHOD
+      self.user_agent       = DEFAULT_USER_AGENT
+    end
+
+    def configure
+      yield self
+    end
+
+    # Return the configuration values set in this module
+    def options
+      Hash[* VALID_CONFIG_KEYS.map { |key| [key, send(key)] }.flatten]
+    end
+  end
+end

data/lib/postcode_anywhere/email_validation/client.rb

@@ -0,0 +1,13 @@
+require 'postcode_anywhere/client'
+require 'postcode_anywhere/email_validation/interactive'
+
+module PostcodeAnywhere
+  module EmailValidation
+    class Client < ::PostcodeAnywhere::Client
+      include PostcodeAnywhere::EmailValidation::Interactive
+      def initialize(options = {})
+        super(options)
+      end
+    end
+  end
+end

data/lib/postcode_anywhere/email_validation/interactive.rb

@@ -0,0 +1,25 @@
+require 'postcode_anywhere/utils'
+require 'postcode_anywhere/email_validation/validation_result'
+
+module PostcodeAnywhere
+  module EmailValidation
+    module Interactive
+      include ::PostcodeAnywhere::Utils
+
+      API_VERSION = '1.10'
+
+      VALIDATE_EMAIL_ENDPOINT =
+        "/EmailValidation/Interactive/Validate/v#{API_VERSION}/json3.ws"
+
+      def validate_email_address(email, timeout = 3, options = {})
+        options.merge!('Email' => email, 'Timeout' => timeout)
+        perform_with_object(
+          :get,
+          VALIDATE_EMAIL_ENDPOINT,
+          options,
+          PostcodeAnywhere::EmailValidation::ValidationResult
+        )
+      end
+    end
+  end
+end

data/lib/postcode_anywhere/email_validation/validation_result.rb

@@ -0,0 +1,24 @@
+require 'postcode_anywhere/model_base'
+
+module PostcodeAnywhere
+  module EmailValidation
+    class ValidationResult < PostcodeAnywhere::ModelBase
+      # The address the email was sent to.
+      # Example: info@google.com
+      attr_reader :email
+
+      # The mail server that was used to perform the server and account validation steps on.
+      # Not populated if the DNS record was not found.
+      # Example: google.com.s9a1.psmtp.com
+      attr_reader :mail_server
+
+      # Indicates that the format of the email appears valid.
+      # Example: true
+      attr_reader :valid_format
+
+      # Indicates that a valid DNS record was found for the email.
+      # Example: true
+      attr_reader :found_dns_record
+    end
+  end
+end

data/lib/postcode_anywhere/error.rb

@@ -0,0 +1,118 @@
+module PostcodeAnywhere
+  # Custom error class for rescuing from all PostcodeAnywhere errors
+  class Error < StandardError
+    attr_reader :code
+    attr_reader :cause
+    attr_reader :resolution
+
+    class << self
+      def from_response(error_hash)
+        message, code, cause, resolution = parse_error(error_hash)
+        new(message, code, cause, resolution)
+      end
+
+      def errors
+        @errors ||= {
+          400 => PostcodeAnywhere::Error::BadRequest,
+          401 => PostcodeAnywhere::Error::Unauthorized,
+          403 => PostcodeAnywhere::Error::Forbidden,
+          404 => PostcodeAnywhere::Error::NotFound,
+          406 => PostcodeAnywhere::Error::NotAcceptable,
+          408 => PostcodeAnywhere::Error::RequestTimeout,
+          422 => PostcodeAnywhere::Error::UnprocessableEntity,
+          429 => PostcodeAnywhere::Error::TooManyRequests,
+          500 => PostcodeAnywhere::Error::InternalServerError,
+          502 => PostcodeAnywhere::Error::BadGateway,
+          503 => PostcodeAnywhere::Error::ServiceUnavailable,
+          504 => PostcodeAnywhere::Error::GatewayTimeout
+        }
+      end
+
+      def postcode_anywhere_errors
+        @postcode_anywhere_errors ||= {
+          -1 => PostcodeAnywhere::Error::UnknownError,
+          2  => PostcodeAnywhere::Error::UnknownKey,
+          3  => PostcodeAnywhere::Error::AccountOutOfCredit,
+          4  => PostcodeAnywhere::Error::IpDenied,
+          5  => PostcodeAnywhere::Error::UrlDenied,
+          6  => PostcodeAnywhere::Error::ServiceDeniedForKey,
+          7  => PostcodeAnywhere::Error::ServiceDeniedForPlan,
+          8  => PostcodeAnywhere::Error::KeyDailyLimitExceeded,
+          9  => PostcodeAnywhere::Error::SurgeProtectorRunning,
+          10 => PostcodeAnywhere::Error::SurgeProtectorTriggered,
+          11 => PostcodeAnywhere::Error::NoValidLicense,
+          12 => PostcodeAnywhere::Error::ManagementKeyRequired,
+          13 => PostcodeAnywhere::Error::DemoLimitExceeded,
+          14 => PostcodeAnywhere::Error::FreeLimitExceeded,
+          15 => PostcodeAnywhere::Error::IncorrectKeyType,
+          16 => PostcodeAnywhere::Error::KeyExpired,
+          17 => PostcodeAnywhere::Error::KeyDailyLimitExceeded
+        }
+      end
+
+      private
+
+      def parse_error(error_hash)
+        if error_hash.nil?
+          ['', nil, '', '']
+        else
+          [
+            error_hash[:description],
+            error_hash[:error],
+            error_hash[:cause],
+            error_hash[:resolution]
+          ]
+        end
+      end
+
+      def extract_message_from_error(body)
+        m =
+          /The exception message is \'(.+)?\'\. See server logs for more details./.match(body)
+        return m.captures.first if m
+      end
+    end
+
+    def initialize(description = '', code = nil, cause = '', resolution = '')
+      super(description)
+      @code = code
+      @cause = cause
+      @resolution = resolution
+    end
+
+    ClientError = Class.new(self)
+    BadRequest = Class.new(ClientError)
+    Unauthorized = Class.new(ClientError)
+    Forbidden = Class.new(ClientError)
+    NotFound = Class.new(ClientError)
+    NotAcceptable = Class.new(ClientError)
+    RequestTimeout = Class.new(ClientError)
+    UnprocessableEntity = Class.new(ClientError)
+    TooManyRequests = Class.new(ClientError)
+    ServerError = Class.new(self)
+    InternalServerError = Class.new(ServerError)
+    BadGateway = Class.new(ServerError)
+    ServiceUnavailable = Class.new(ServerError)
+    GatewayTimeout = Class.new(ServerError)
+
+    # Postcode anywhere specific errors
+
+    UnknownError = Class.new(ServerError)
+    UnknownKey = Class.new(ClientError)
+    AccountOutOfCredit = Class.new(Forbidden)
+    IpDenied = Class.new(Forbidden)
+    UrlDenied = Class.new(Forbidden)
+    ServiceDeniedForKey = Class.new(Forbidden)
+    ServiceDeniedForPlan = Class.new(Forbidden)
+    KeyDailyLimitExceeded = Class.new(Forbidden)
+    SurgeProtectorRunning = Class.new(Forbidden)
+    SurgeProtectorTriggered = Class.new(Forbidden)
+    NoValidLicense = Class.new(Forbidden)
+    ManagementKeyRequired = Class.new(Forbidden)
+    DemoLimitExceeded = Class.new(Forbidden)
+    FreeLimitExceeded = Class.new(Forbidden)
+    IncorrectKeyType = Class.new(Forbidden)
+    KeyExpired = Class.new(Forbidden)
+
+    ServiceSpecificError = Class.new(ClientError)
+  end
+end

data/lib/postcode_anywhere/model_base.rb

@@ -0,0 +1,72 @@
+require 'memoizable'
+
+module PostcodeAnywhere
+  class ModelBase
+    include Memoizable
+    attr_reader :attrs
+    alias_method :to_h, :attrs
+    alias_method :to_hash, :to_h
+
+    class << self
+      def attr_reader(*attrs)
+        attrs.each do |attr|
+          define_attribute_method(attr)
+          define_predicate_method(attr)
+        end
+      end
+
+      def predicate_attr_reader(*attrs)
+        attrs.each do |attr|
+          define_predicate_method(attr)
+          deprecate_attribute_method(attr)
+        end
+      end
+
+      def object_attr_reader(klass, key1, key2 = nil)
+        define_attribute_method(key1, klass, key2)
+        define_predicate_method(key1)
+      end
+
+      def define_attribute_method(key1, klass = nil, key2 = nil)
+        define_method(key1) do ||
+          if @attrs[key1].nil? || @attrs[key1].respond_to?(:empty?) && @attrs[key1].empty?
+            # NullObject.new
+          else
+            if klass.nil?
+              @attrs[key1]
+            else
+              attrs = attrs_for_object(key1, key2)
+              PostcodeAnywhere.const_get(klass).new(attrs)
+            end
+          end
+        end
+        memoize(key1)
+      end
+
+      def define_predicate_method(key1, key2 = key1)
+        define_method(:"#{key1}?") do ||
+          !@attrs[key2].nil? &&
+          @attrs[key2] != false &&
+          !(@attrs[key2].respond_to?(:empty?) &&
+          @attrs[key2].empty?)
+        end
+        memoize(:"#{key1}?")
+      end
+    end
+
+    def initialize(attrs = {})
+      @attrs = attrs || {}
+    end
+
+    private
+
+    def attrs_for_object(key1, key2 = nil)
+      if key2.nil?
+        @attrs[key1]
+      else
+        attrs = @attrs.dup
+        attrs.delete(key1).merge(key2 => attrs)
+      end
+    end
+  end
+end

data/lib/postcode_anywhere/request.rb

@@ -0,0 +1,33 @@
+module PostcodeAnywhere
+  class Request
+    attr_accessor :client, :request_method, :path, :body, :options
+    alias_method :verb, :request_method
+
+    def initialize(client, request_method, path, body_hash = {}, options = {})
+      @client = client
+      @request_method = request_method.to_sym
+      @path = path
+      @body_hash = body_hash
+      @options = options
+    end
+
+    def perform
+      @client.send(@request_method, @path, @body_hash, @options).body
+    end
+
+    def perform_with_object(klass)
+      result = perform
+      if result.class == Array
+        klass.new(result.first)
+      else
+        klass.new(result)
+      end
+    end
+
+    def perform_with_objects(klass)
+      perform.map do |element|
+        klass.new(element)
+      end
+    end
+  end
+end