firstclasspostcodes 0.0.1

data/lib/firstclasspostcodes/events.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Firstclasspostcodes
+  module Events
+    def on(event_name, &handler)
+      event_symbol = event_name.to_sym
+      events[event_symbol] ||= []
+      events[event_symbol].push(handler)
+      handler.object_id
+    end
+
+    def off(event_name, handler_id)
+      events[event_name.to_sym]&.filter! do |handler|
+        handler.object_id != handler_id
+      end
+      handler_id
+    end
+
+    def emit(event_name, *args)
+      events[event_name.to_sym]&.each { |handler| handler.call(*args) }
+    end
+
+    def events
+      @events ||= {}
+    end
+  end
+end

data/lib/firstclasspostcodes/operations.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "operations/get_postcode"
+require_relative "operations/get_lookup"

data/lib/firstclasspostcodes/operations/get_lookup.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Firstclasspostcodes
+  module Operations
+    module GetLookup
+      def get_lookup(params)
+        raise StandError, "Expected hash, received: #{params}" unless params.is_a?(Hash)
+
+        error_object = nil
+
+        parse_f = ->(val) { val.to_f.to_s == val ? val.to_f : nil }
+
+        within = ->(lat, lng) { (lat >= -90 && lat <= 90) && (lng >= -180 && lng <= 180) }
+
+        unless params[:latitude] || params[:longitude]
+          error_object = {
+            message: "Missing required parameters, expected { latitude, longitude }.",
+            docUrl: "https://docs.firstclasspostcodes.com/operation/getLookup",
+          }
+        end
+
+        latitude = parse_f.call(params[:latitude])
+        longitude = parse_f.call(params[:longitude])
+        radius = parse_f.call(params[:radius]) || 0.1
+
+        query_params =  { latitude: latitude, longitude: longitude, radius: radius }
+
+        unless latitude && longitude && within.call(latitude, longitude)
+          error_object = {
+            message: "Parameter is invalid: #{query_params}",
+            docUrl: "https://docs.firstclasspostcodes.com/operation/getLookup",
+          }
+        end
+
+        request_params = { path: "/lookup", method: :get, query_params: query_params }
+
+        @config.logger.debug("Executing operation getLookup: #{request_params}") if @config.debug?
+
+        emit("operation:getLookup", request_params)
+
+        if error_object
+          error = StandardError.new(error_object)
+          @config.logger.debug("Encountered ParameterValidationError: #{error}")
+          emit("error", error)
+          raise error
+        end
+
+        request(request_params)
+      end
+    end
+  end
+end

data/lib/firstclasspostcodes/operations/get_postcode.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "methods/list_addresses"
+require_relative "methods/format_address"
+
+module Firstclasspostcodes
+  module Operations
+    module GetPostcode
+      def get_postcode(postcode)
+        error_object = nil
+
+        if !postcode.is_a?(String) || postcode.empty?
+          error_object = {
+            message: "Unexpected postcode parameter: '#{postcode}'",
+            docUrl: "https://docs.firstclasspostcodes.com/operation/getPostcode",
+          }
+        end
+
+        request_params = { method: :get, path: "/postcode", query_params: { search: postcode } }
+
+        @config.logger.debug("Executing operation getPostcode: #{request_params}") if @config.debug?
+
+        emit("operation:getPostcode", request_params)
+
+        if error_object
+          error = StandardError.new(error_object)
+          @config.logger.debug("Encountered ParameterValidationError: #{error}")
+          emit("error", error)
+          raise error
+        end
+
+        response = request(request_params)
+
+        response.extend(Methods::ListAddresses, Methods::FormatAddress) unless @config.geo_json?
+
+        response
+      end
+    end
+  end
+end

data/lib/firstclasspostcodes/operations/methods/format_address.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Firstclasspostcodes
+  module Operations
+    module Methods
+      module FormatAddress
+        def format_address(index)
+          type, element = index.split(":")
+
+          data = {
+            locality: self[:city] || self[:locality],
+            region: self[:county] || self[:region],
+            postcode: self[:postcode],
+            country: self[:country],
+          }
+
+          return data if type == "postcode"
+
+          list = self[type.to_sym]
+
+          index = element.to_i
+
+          raise StandardError, `Received index "#{index}" but no #{type} data.` if list.empty?
+
+          address = if type == "numbers"
+                      component = list[index]
+                      join = ->(*args) { args.compact.reject(&:empty?).join(", ") }
+                      join.call(component[:number], component[:building], component[:street])
+                    else
+                      list[index]
+                    end
+
+          data.merge(address: address)
+        end
+      end
+    end
+  end
+end

data/lib/firstclasspostcodes/operations/methods/list_addresses.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Firstclasspostcodes
+  module Operations
+    module Methods
+      module ListAddresses
+        def list_addresses
+          join = ->(*args) { args.compact.reject(&:empty?).join(", ") }
+
+          suffix = join.call(self[:city] || self[:locality], self[:postcode])
+
+          if self[:numbers]&.any?
+            return self[:numbers].each_with_index.map do |number, i|
+              %W[numbers:#{i} #{join.call(number[:number], number[:building], number[:street], suffix)}]
+            end
+          end
+
+          if self[:streets]&.any?
+            return self[:streets].each_with_index.map do |street, i|
+              %W[streets:#{i} #{join.call(street, suffix)}]
+            end
+          end
+
+          [%W[postcode:0 #{suffix}]]
+        end
+      end
+    end
+  end
+end

data/lib/firstclasspostcodes/response_error.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+DOC_URL = "https://docs.firstclasspostcodes.com/ruby/errors"
+
+module Firstclasspostcodes
+  class ResponseError < StandardError
+    attr_reader :doc_url, :type
+
+    def initialize(obj, type = nil)
+      if obj.is_a?(Hash)
+        super(obj[:message])
+        @doc_url = obj[:docUrl]
+        @type = obj[:type]
+        return
+      end
+      super(obj)
+      @doc_url = "#{DOC_URL}/#{type}"
+      @type = type
+    end
+
+    def message
+      <<-MSG
+        The following "#{type}" error was encountered:
+          #{super}
+        => See: #{doc_url}
+      MSG
+    end
+  end
+end

data/lib/firstclasspostcodes/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Firstclasspostcodes
+  VERSION = "0.0.1"
+end

data/spec/firstclasspostcodes/client_spec.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "json"
+
+require_relative "../support/events_examples.rb"
+
+describe Firstclasspostcodes::Client do
+  subject { Firstclasspostcodes::Client.new }
+
+  it_behaves_like "a class that emits events" do
+    subject { Firstclasspostcodes::Client.new }
+  end
+
+  specify { expect(subject).to respond_to(:get_postcode) }
+
+  specify { expect(subject).to respond_to(:get_lookup) }
+
+  describe "#config" do
+    specify { expect(subject.config).to be_instance_of(Firstclasspostcodes::Configuration) }
+  end
+
+  describe "#user_agent" do
+    specify { expect(subject).not_to respond_to(:user_agent=) }
+
+    specify { expect(subject.user_agent).to include Firstclasspostcodes::VERSION }
+  end
+
+  describe "#request" do
+    describe "when the request is successful" do
+      let(:response) { double(body: '{"a": 1 }') }
+
+      let(:request_params) { { method: :get, path: "/" } }
+
+      before(:each) { allow(subject).to receive(:call_request).with(kind_of(String), kind_of(Hash)).and_return(response) }
+
+      it "returns a parsed response" do
+        expect(subject.request(request_params)).to eq(a: 1)
+      end
+    end
+  end
+
+  describe "#call_request" do
+    describe "successful request" do
+      let(:stubbed_response) { Typhoeus::Response.new(code: 200, body: "test") }
+
+      before(:each) { Typhoeus.stub(/test/).and_return(stubbed_response) }
+
+      specify { expect(subject.call_request("www.test.com")).to eq(stubbed_response) }
+    end
+
+    describe "unsuccessful request" do
+      let(:stubbed_response) { Typhoeus::Response.new(code: 403, body: "forbidden") }
+
+      before(:each) { Typhoeus.stub(/test/).and_return(stubbed_response) }
+
+      before(:each) { instance_double }
+    end
+  end
+
+  describe "#handle_request_error" do
+    describe "when request is timed out" do
+      let(:response) { double(timed_out?: true) }
+
+      specify { expect { subject.handle_request_error(response) }.to raise_error(Firstclasspostcodes::ResponseError) }
+    end
+
+    describe "when there was a libcurl error" do
+      let(:response) { double(timed_out?: false, code: 0, return_message: "message") }
+
+      specify { expect { subject.handle_request_error(response) }.to raise_error(Firstclasspostcodes::ResponseError) }
+    end
+
+    describe "when there was an api error" do
+      describe "when the response is JSON" do
+        let(:response) { double(timed_out?: false, code: 500, body: '{ "err": "message" }') }
+
+        specify { expect { subject.handle_request_error(response) }.to raise_error(Firstclasspostcodes::ResponseError) }
+      end
+
+      describe "when the response cannot be parsed" do
+        let(:response) { double(timed_out?: false, code: 500, body: "error message") }
+
+        specify { expect { subject.handle_request_error(response) }.to raise_error(Firstclasspostcodes::ResponseError) }
+      end
+    end
+  end
+
+  describe "#build_request_url" do
+    let(:path) { "/test" }
+
+    specify { expect(subject.build_request_url(path)).to include path }
+  end
+end

data/spec/firstclasspostcodes/events_spec.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "json"
+
+describe Firstclasspostcodes::Events do
+  class TestEvents
+    include Firstclasspostcodes::Events
+  end
+
+  subject { TestEvents.new }
+
+  let(:event_name) { "test" }
+
+  let(:handler) { proc { nil } }
+
+  describe "#on" do
+    it "should add a handler for a specific event" do
+      expect(subject.on(event_name, &handler)).to eq(handler.object_id)
+      expect(subject.events[event_name.to_sym]).to eq([handler])
+    end
+  end
+
+  describe "#off" do
+    before(:each) { subject.on(event_name, &handler) }
+
+    it "should remove a handler for a specific event" do
+      subject.off(event_name, handler.object_id)
+      expect(subject.events[event_name.to_sym]).to eq([])
+    end
+  end
+
+  describe "#emit" do
+    it "should emit an event" do
+      expect do |b|
+        subject.on(event_name, &b)
+        subject.emit(event_name, 1)
+      end.to yield_with_args(1)
+    end
+  end
+end

data/spec/firstclasspostcodes/operations/get_lookup_spec.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+describe Firstclasspostcodes::Operations::GetLookup do
+  class TestGetLookup
+    attr_accessor :config
+
+    include Firstclasspostcodes::Operations::GetLookup
+
+    def emit(event_name, properties); end
+
+    def request(params); end
+  end
+
+  subject { TestGetLookup.new }
+
+  let(:operation_params) { { path: "/lookup", method: :get } }
+
+  let(:config) { double(debug?: true, logger: double(debug: nil)) }
+
+  before(:each) { allow(subject).to receive(:emit).with(anything, anything).and_return(true) }
+
+  before(:each) { subject.config = config }
+
+  specify { expect(subject).respond_to?(:get_lookup) }
+
+  describe "when the request is valid" do
+    before(:each) { allow(subject).to receive(:request).and_return(nil) }
+
+    let(:params) { { latitude: "52.3456", longitude: "-0.2567" } }
+
+    it "resolves with the correct request parameters" do
+      expected_request_params = operation_params.merge(
+        query_params: {
+          latitude: params[:latitude].to_f,
+          longitude: params[:longitude].to_f,
+          radius: anything,
+        }
+      )
+
+      expect(subject).to receive(:request).with(expected_request_params)
+    end
+
+    after(:each) { subject.get_lookup(params) }
+  end
+
+  describe "when the request is invalid" do
+    describe "when there are no request options" do
+      it "raises an error" do
+        expect { subject.get_lookup("sertgh") }.to raise_error(StandardError)
+      end
+    end
+
+    describe "when the latitude is invalid" do
+      let(:params) { { latitude: "4567.123", longitude: "-0.2567" } }
+
+      it "raises an error" do
+        expect { subject.get_lookup(params) }.to raise_error(StandardError)
+      end
+    end
+
+    describe "when the latitude is incorrect" do
+      let(:params) { { latitude: "aaaaa", longitude: "-0.2567" } }
+
+      it "raises an error" do
+        expect { subject.get_lookup(params) }.to raise_error(StandardError)
+      end
+    end
+
+    describe "when the latitude is missing" do
+      let(:params) { { longitude: "-0.2567" } }
+
+      it "raises an error" do
+        expect { subject.get_lookup(params) }.to raise_error(StandardError)
+      end
+    end
+
+    describe "when the longitude is invalid" do
+      let(:params) { { latitude: "56.123", longitude: "-23456.2567" } }
+
+      it "raises an error" do
+        expect { subject.get_lookup(params) }.to raise_error(StandardError)
+      end
+    end
+
+    describe "when the longitude is incorrect" do
+      let(:params) { { latitude: "56.123", longitude: "ertyhgfd" } }
+
+      it "raises an error" do
+        expect { subject.get_lookup(params) }.to raise_error(StandardError)
+      end
+    end
+
+    describe "when the longitude is missing" do
+      let(:params) { { latitude: "56.123" } }
+
+      it "raises an error" do
+        expect { subject.get_lookup(params) }.to raise_error(StandardError)
+      end
+    end
+  end
+end