firstclasspostcodes 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4e926c2b2819dd25138a2df749f49930a486e220d9846766855a9b31dba92d8b
+  data.tar.gz: 3094812034c5a12258c3d8dccc87c0add4d9e173b4011657ac4c7dab564e314e
+SHA512:
+  metadata.gz: 2ee17eead9837df323e51afcaa91c19b7d9263d59349c4364493ac0fd85f400c3a199cc041582834488e11324afa8946920c2023fa08c4332b153dc23293c39d
+  data.tar.gz: 48310e7b50ca7a3de522c393f835e678706e31a4c6ae14f1eda6c7ba5686a1099b18eb4bc2d94998bae8bc2a3c0605aa5de6e04d15636eb302a162c411175a29

data/.dependabot/config.yml

@@ -0,0 +1,12 @@
+version: 1
+
+update_configs:
+
+  - package_manager: "ruby:bundler"
+    directory: "/"
+    update_schedule: "weekly"
+    version_requirement_updates: increase_versions
+    automerged_updates:
+      - match:
+          dependency_type: "all"
+          update_type: "all"

data/.github/workflows/gem.yml

@@ -0,0 +1,53 @@
+name: "Build, test and release"
+
+on:
+  - push
+  - pull_request
+
+jobs:
+  build:
+    name: Build + Publish
+    runs-on: ubuntu-latest
+
+    services:
+      mock-api:
+        image: firstclasspostcodes/mock:latest
+        ports:
+          - '80:3000'
+
+    steps:
+      - uses: actions/checkout@master
+      - name: Set up Ruby 2.6
+        uses: actions/setup-ruby@v1
+        with:
+          version: 2.6.x
+      - run: gem install bundler
+      - run: bundle install --jobs 4 --retry 3
+      - name: Rake
+        run: bundle exec rake
+        env:
+          API_URL: http://localhost:3000
+          API_KEY: '111111111111'
+      - name: Publish to GPR
+        if: github.ref == 'refs/heads/master'
+        run: |
+          mkdir -p $HOME/.gem
+          touch $HOME/.gem/credentials
+          chmod 0600 $HOME/.gem/credentials
+          printf -- "---\n:github: Bearer ${GITHUB_TOKEN}\n" > $HOME/.gem/credentials
+          gem build *.gemspec
+          gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem
+        env:
+          OWNER: firstclasspostcodes
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+      - name: Publish to RubyGems
+        if: github.ref == 'refs/heads/master'
+        run: |
+          mkdir -p $HOME/.gem
+          touch $HOME/.gem/credentials
+          chmod 0600 $HOME/.gem/credentials
+          printf -- "---\n:rubygems_api_key: ${RUBYGEMS_AUTH_TOKEN}\n" > $HOME/.gem/credentials
+          gem build *.gemspec
+          gem push *.gem
+        env:
+          RUBYGEMS_AUTH_TOKEN: ${{secrets.RUBYGEMS_AUTH_TOKEN}}

data/.gitignore

@@ -0,0 +1,9 @@
+/firstclasspostcodes-*.gem
+/Gemfile.lock
+.rvmrc
+Gemfile.lock
+tags
+vendor
+/.bundle/
+coverage/
+.idea/

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,78 @@
+AllCops:
+  DisplayCopNames: true
+  TargetRubyVersion: 2.3
+
+  Exclude:
+    # brandur: Exclude ephmeral script-like files that I use to try and
+    # reproduce problems with the library. If you know of a better way of doing
+    # this (e.g. exclude files not tracked by Git), feel free to change it.
+    - "test_*"
+
+Layout/CaseIndentation:
+  EnforcedStyle: end
+
+Layout/FirstArrayElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+
+# This can be re-enabled once we're 2.3+ only and can use the squiggly heredoc
+# operator. Prior to that, Rubocop recommended bringing in a library like
+# ActiveSupport to get heredoc indentation, which is just terrible.
+Layout/HeredocIndentation:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 150
+  Exclude:
+    - "spec/**/*.rb"
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    # `context` in tests are blocks and get quite large, so exclude the test
+    # directory from having to adhere to this rule.
+    - "spec/**/*.rb"
+
+Metrics/ClassLength:
+  Exclude:
+    # Test classes get quite large, so exclude the test directory from having
+    # to adhere to this rule.
+    - "test/**/*.rb"
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Max: 50
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/AccessModifierDeclarations:
+  EnforcedStyle: inline
+
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: always
+
+Style/NumericPredicate:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: consistent_comma

data/Gemfile

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "codecov", require: false
+  gem "coveralls", require: false
+  gem "rake"
+  gem "rspec"
+
+  # Rubocop changes pretty quickly: new cops get added and old cops change
+  # names or go into new namespaces. This is a library and we don't have
+  # `Gemfile.lock` checked in, so to prevent good builds from suddenly going
+  # bad, pin to a specific version number here. Try to keep this relatively
+  # up-to-date, but it's not the end of the world if it's not.
+  gem "rubocop", "0.79", require: false
+
+  platforms :mri do
+    gem "byebug"
+    gem "pry"
+    gem "pry-byebug"
+  end
+end

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2018-2020 Firstclasspostcodes (https://firstclasspostcodes.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/firstclasspostcodes.gemspec

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(::File.join(::File.dirname(__FILE__), "lib"))
+
+require "firstclasspostcodes/version"
+
+REPO_URL = "github.com/firstclasspostcodes/firstclasspostcodes-ruby"
+
+DOMAIN_NAME = "firstclasspostcodes.com"
+
+Gem::Specification.new do |s|
+  s.name = "firstclasspostcodes"
+
+  s.version = Firstclasspostcodes::VERSION
+
+  s.required_ruby_version = ">= 2.3.0"
+
+  s.summary = <<-SUMMARY
+    Ruby bindings for the Firstclasspostcodes API
+  SUMMARY
+
+  s.description = <<-DESC
+    With 500 requests for free per month, get started with the
+    fastest and cheapest address lookup service in the UK.
+
+    See https://#{DOMAIN_NAME} for more details.
+  DESC
+
+  s.author = "Firstclasspostcodes"
+
+  s.email = "support@#{DOMAIN_NAME}"
+
+  s.homepage = "https://docs.#{DOMAIN_NAME}"
+
+  s.license = "MIT"
+
+  s.metadata = {
+    "bug_tracker_uri" => "https://#{REPO_URL}/issues",
+    "changelog_uri" => "https://#{REPO_URL}/blob/master/CHANGELOG.md",
+    "documentation_uri" => "https://docs.#{DOMAIN_NAME}",
+    "github_repo" => "ssh://#{REPO_URL}",
+    "homepage_uri" => "https://#{DOMAIN_NAME}",
+    "source_code_uri" => "https://#{REPO_URL}",
+  }
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- test/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n")
+                                           .map { |f| ::File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency "json", "~> 2.2", ">= 2.2.0"
+  s.add_runtime_dependency "typhoeus", "~> 1.3", ">= 1.3.1"
+end

data/lib/firstclasspostcodes.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "firstclasspostcodes/client"
+require "firstclasspostcodes/configuration"
+require "firstclasspostcodes/events"
+require "firstclasspostcodes/operations"
+require "firstclasspostcodes/version"
+
+module Firstclasspostcodes
+  class << self
+    # Customize default settings for the SDK using block.
+    #   Firstclasspostcodes.configure do |config|
+    #     config.api_key = "xxx"
+    #   end
+    # If no block given, return the default Configuration object.
+    def configure
+      if block_given?
+        yield(Configuration.default)
+      else
+        Configuration.default
+      end
+    end
+  end
+
+  class Client
+    # Utility module mixins
+    include Events
+
+    # Include all API operations below
+    include Operations::GetPostcode
+    include Operations::GetLookup
+  end
+end

data/lib/firstclasspostcodes/client.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+require "typhoeus"
+
+require "firstclasspostcodes/response_error"
+
+module Firstclasspostcodes
+  class Client
+    # The Configuration object holding settings to be used in the API client.
+    attr_accessor :config
+
+    # The User-agent for the library
+    attr_reader :user_agent
+
+    # @option config [Configuration] Configuration for initializing the object
+    def initialize(config = Configuration.default)
+      @config = config
+      @user_agent = "Firstclasspostcodes/ruby@#{Firstclasspostcodes::VERSION}"
+      on("request") { |req| @config.logger.debug(req) if @config.debug }
+      on("response") { |req| @config.logger.debug(req) if @config.debug }
+      on("error") { |req| @config.logger.error(req) }
+    end
+
+    def request(opts)
+      url = build_request_url(opts[:path])
+
+      request_params = {
+        params: opts[:query_params] || {},
+        method: opts[:method].to_sym.downcase,
+      }
+
+      request_params.merge!(@config.to_request_params)
+
+      emit("request", request_params)
+
+      response = call_request(url, request_params)
+
+      data = JSON.parse(response.body, symbolize_names: true)
+
+      emit("response", data)
+
+      data
+    rescue ResponseError => e
+      emit("error", e)
+      raise e
+    end
+
+    def call_request(*args)
+      response = Typhoeus::Request.new(*args).run
+
+      return response if response.success?
+
+      raise handle_request_error(response)
+    end
+
+    def handle_request_error(response)
+      raise ResponseError.new("Connection timed out", "timeout") if response.timed_out?
+
+      raise ResponseError.new(response.return_message, "liberror") if response.code == 0
+
+      error = begin
+                JSON.parse(response.body, symbolize_names: true)
+              rescue JSON::ParserError
+                response.body
+              end
+
+      raise ResponseError.new(error, "network-error")
+    end
+
+    def build_request_url(path)
+      # Add leading and trailing slashes to path
+      path = "/#{path}".gsub(%r{/+}, "/")
+      @config.base_url + path
+    end
+
+    def self.default
+      @default ||= Client.new
+    end
+  end
+end

data/lib/firstclasspostcodes/configuration.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Firstclasspostcodes
+  class Configuration
+    # Defines API keys used with API Key authentications.
+    #
+    # @return [String] the value of the API key being used
+    #
+    # @example parameter name is "api_key", API key is "xxx"
+    #   config.api_key['api_key'] = 'xxx'
+    attr_accessor :api_key
+
+    # Defines url host
+    attr_reader :host
+
+    # Defines the content type requested and returned
+    attr_reader :content
+
+    # Defines HTTP protocol to be used
+    attr_reader :protocol
+
+    # Defines url base path
+    attr_reader :base_path
+
+    # Defines the logger used for debugging.
+    # Default to `Rails.logger` (when in Rails) or logging to STDOUT.
+    #
+    # @return [#debug]
+    attr_accessor :logger
+
+    # Set this to enable/disable debugging. When enabled (set to true), HTTP request/response
+    # details will be logged with `logger.debug` (see the `logger` attribute).
+    # Default to false.
+    #
+    # @return [true, false]
+    attr_accessor :debug
+
+    # The time limit for HTTP request in seconds.
+    # Default to 0 (never times out).
+    attr_accessor :timeout
+
+    ### TLS/SSL setting
+    # Set this to false to skip verifying SSL certificate when calling API from https server.
+    # Default to true.
+    #
+    # @note Do NOT set it to false in production code, otherwise you would face multiple types of cryptographic attacks.
+    #
+    # @return [true, false]
+    attr_accessor :verify_ssl
+
+    ### TLS/SSL setting
+    # Set this to false to skip verifying SSL host name
+    # Default to true.
+    #
+    # @note Do NOT set it to false in production code, otherwise you would face multiple types of cryptographic attacks.
+    #
+    # @return [true, false]
+    attr_accessor :verify_ssl_host
+
+    ### TLS/SSL setting
+    # Set this to customize the certificate file to verify the peer.
+    #
+    # @return [String] the path to the certificate file
+    #
+    # @see The `cainfo` option of Typhoeus, `--cert` option of libcurl. Related source code:
+    # https://github.com/typhoeus/typhoeus/blob/master/lib/typhoeus/easy_factory.rb#L145
+    attr_accessor :ssl_ca_cert
+
+    ### TLS/SSL setting
+    # Client certificate file (for client certificate)
+    attr_accessor :cert_file
+
+    ### TLS/SSL setting
+    # Client private key file (for client certificate)
+    attr_accessor :key_file
+
+    def initialize
+      @api_key = nil
+      @debug = false
+      @host = "api.firstclasspostcodes.com"
+      @content = "json"
+      @protocol = "https"
+      @base_path = "/data"
+      @timeout = 0
+      @verify_ssl = true
+      @verify_ssl_host = true
+      @cert_file = nil
+      @key_file = nil
+      @logger = defined?(Rails) ? Rails.logger : Logger.new(STDOUT)
+      yield(self) if block_given?
+    end
+
+    # The default Configuration object.
+    def self.default
+      @default ||= Configuration.new
+    end
+
+    def configure
+      yield(self) if block_given?
+    end
+
+    def debug?
+      debug
+    end
+
+    def geo_json?
+      content == "geo+json"
+    end
+
+    def content=(content)
+      raise StandardError, `"#{content}" is not a valid content-type` unless %w[json geo+json].include?(content)
+
+      @content = content
+    end
+
+    def protocol=(protocol)
+      # remove :// from protocol
+      @protocol = protocol.sub(%r{://}, "")
+    end
+
+    def host=(host)
+      # remove http(s):// and anything after a slash
+      @host = host.sub(%r{https?://}, "").split("/").first
+    end
+
+    def base_path=(base_path)
+      # Add leading and trailing slashes to base_path
+      @base_path = "/#{base_path}".gsub(%r{/+}, "/")
+      @base_path = "" if @base_path == "/"
+    end
+
+    def base_url
+      path = [host, base_path].join("/").gsub(%r{/+}, "/")
+      "#{protocol}://#{path}".sub(%r{/+\z}, "")
+    end
+
+    def to_request_params
+      params = {
+        headers: {
+          'x-api-key': api_key,
+          accept: "application/#{content}; q=1.0, application/json; q=0.5",
+        },
+        timeout: timeout,
+        ssl_verifypeer: verify_ssl,
+        ssl_verifyhost: verify_ssl_host ? 2 : 0,
+        sslcert: cert_file,
+        sslkey: key_file,
+        verbose: debug,
+      }
+
+      params[:cainfo] = ssl_ca_cert if ssl_ca_cert
+
+      params
+    end
+  end
+end