firstclasspostcodes 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e926c2b2819dd25138a2df749f49930a486e220d9846766855a9b31dba92d8b
-  data.tar.gz: 3094812034c5a12258c3d8dccc87c0add4d9e173b4011657ac4c7dab564e314e
+  metadata.gz: 1c7ef5f006a609e8cc2a1a7e640df790a62ffcc58f2902bda292f656713864b6
+  data.tar.gz: 7807d503f9aa8aaa3b0de5645afa654229a27c4b8d15076390a82a3023ccfdf2
 SHA512:
-  metadata.gz: 2ee17eead9837df323e51afcaa91c19b7d9263d59349c4364493ac0fd85f400c3a199cc041582834488e11324afa8946920c2023fa08c4332b153dc23293c39d
-  data.tar.gz: 48310e7b50ca7a3de522c393f835e678706e31a4c6ae14f1eda6c7ba5686a1099b18eb4bc2d94998bae8bc2a3c0605aa5de6e04d15636eb302a162c411175a29
+  metadata.gz: 2e27e22f9d6121d354e2fe10b4fff29a436fb5df7f19179fe97378b9341ccb645fbb6ad24e7c5c77b9b65e76a9d04e360629e647a67319170d2858af1fd4b0c5
+  data.tar.gz: 49a18424d3dc1dafbd502569209702fd91c7212c3a96534d590c87dd6d91956c2ed2777f396420eb85cc52b194495625ced803bb09ee1443984d599957459f0c

data/.github/workflows/gem.yml

@@ -12,8 +12,10 @@ jobs:
     services:
       mock-api:
         image: firstclasspostcodes/mock:latest
+        env:
+          PORT: 3000
         ports:
-          - '80:3000'
+          - '3000:3000'
 
     steps:
       - uses: actions/checkout@master

data/README.md

@@ -0,0 +1,179 @@
+![Cover](/.github/images/cover.png)
+
+# Firstclasspostcodes
+The Firstclasspostcodes Ruby library provides convenient access to the Firstclasspostcodes API from applications written in the Ruby language. It includes pre-defined methods and helpers to help you easily integrate the library into any application.
+
+The library also provides other features. For example:
+
+* Easy configuration path for fast setup and use.
+* Helpers for listing and formatting addresses.
+* Built-in methods for easily interacting with the Firstclasspostcodes API.
+
+## Documentation
+See [Ruby API docs](https://docs.firstclasspostcodes.com/ruby/getting-started) for detailed usage and examples.
+
+## Installation
+You don't need this source code unless you want to modify the gem. If you just want to use the package, just run:
+
+```
+gem install firstclasspostcodes
+```
+
+Or alternatively, install from the GitHub package registry:
+
+```
+gem install firstclasspostcodes --source "https://rubygems.pkg.github.com/firstclasspostcodes"
+```
+
+If you want to build the gem from source:
+
+```
+gem build firstclasspostcodes.gemspec
+```
+
+## Requirements
+
+* Ruby 2.3+
+* An API key from [https://firstclasspostcodes.com](https://firstclasspostcodes.com)
+
+## Bundler
+
+If you are installing via bundler, you should be sure to use the https rubygems source in your Gemfile, as any gems fetched over http could potentially be compromised in transit and alter the code of gems fetched securely over https:
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'rails'
+gem 'firstclasspostcodes'
+```
+
+We also host this gem on the [GitHub Package Registry](https://github.com/firstclasspostcodes/firstclasspostcodes-ruby/packages/108443):
+
+```ruby
+source "https://rubygems.pkg.github.com/firstclasspostcodes" do
+  gem "firstclasspostcodes", "0.1.0"
+end
+```
+
+## Usage
+Once you have configured the library, initialise a client and start calling the API.
+
+```ruby
+require 'firstclasspostcodes'
+require 'json'
+
+Firstclasspostcodes.configure do |c|
+  c.api_key = 'sw34567ujbvcd'
+end
+
+client = Firstclasspostcodes::Client.new
+
+response = client.get_postcode('SW13 6HY')
+
+puts JSON.pretty_generate(response)
+```
+
+## Configuration
+The library can be configured with several options depending on the requirements of your setup:
+
+```ruby
+require 'firstclasspostcodes'
+
+API_KEY = 'werthj75rtfgds'
+
+Firstclasspostcodes.configure do |c|
+  # The API Key to be used when sending requests to the 
+  # Firstclasspostcodes API
+  c.api_key = API_KEY
+
+  # The host to send API requests to. This is typically changed
+  # to use the mock service for testing purposes
+  c.host = "api.firstclasspostcodes.com"
+  
+  # The default content type is json, but can be changed to "geo+json"
+  # to return responses as GeoJSON content type
+  c.content = "json"
+
+  # Typically, always HTTPS, but useful to change for testing
+  # purposes
+  c.protocol = "https"
+
+  # The base path is "/data", but useful to change for testing
+  # purposes
+  c.base_path = "/data"
+  
+  # The default logger being used with the library. This defaults
+  # to the Rails logger (if it is available)
+  c.logger = Logger.new(STDOUT)
+
+  # Output helpful debug statements to STDOUT
+  c.debug = false
+
+  # The default request timeout for the library.
+  c.timeout = 30
+end
+```
+
+## Events
+You can subscribe to events using an initialized client, using the Ruby block pattern.
+
+```ruby
+require 'firstclasspostcodes'
+require 'json'
+
+client = Firstclasspostcodes::Client.new
+
+client.on(:request) do |request_params|
+  puts JSON.pretty_generate(request_params)
+end
+```
+
+| Event name | Description |
+|:-----|:-----|
+| `request` | Triggered before a request is sent. The request object to be sent is passed to the event handler. |
+| `response` | Triggered with the parsed JSON response body upon a successful reques. |
+| `error` | Triggered with a client error when the request fails. |
+| `operation:{name}` | Triggered by an operation with the parameter object. |
+
+**Note:** `{name}` is replaced with the operation name of the method, as defined inside the OpenAPI specification.
+
+## Debugging
+Debugging through logging can be enabled inside the configuration (demonstrated below). A custom logger can also be assigned if required.
+
+```ruby
+require 'firstclasspostcodes'
+require 'logger'
+
+custom_logger = Logger.new(STDOUT)
+custom_logger.level = Logger::DEBUG
+
+Firstclasspostcodes.configure do |c|
+  c.debug = true
+  c.logger = custom_logger
+end
+```
+
+## Integration / Testing
+We provide a mock service of our API as a docker container [available here](https://github.com/firstclasspostcodes/firstclasspostcodes-mock). Once the container is running, the library can be easily configured to use it:
+
+```ruby
+require "firstclasspostcodes"
+require "uri"
+
+MOCK_API_URL = "http://localhost:3000"
+
+MOCK_API_KEY = "111111111111"
+
+uri = URI.parse(MOCK_API_URL)
+
+Firstclasspostcodes.configure do |c|
+  # The mock API key is always 111111111111 ("12x1")
+  c.api_key = MOCK_API_KEY
+  
+  # Alter the configuration to use the mock service
+  c.base_path = uri.path
+  c.protocol = uri.scheme
+  c.host = uri.host
+  c.host = "#{uri.host}:#{uri.port}" if uri.port
+end
+```

data/lib/firstclasspostcodes/configuration.rb

@@ -81,7 +81,7 @@ module Firstclasspostcodes
       @content = "json"
       @protocol = "https"
       @base_path = "/data"
-      @timeout = 0
+      @timeout = 30
       @verify_ssl = true
       @verify_ssl_host = true
       @cert_file = nil

data/lib/firstclasspostcodes/version.rb

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

data/spec/firstclasspostcodes/integration_spec.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "json"
+
+require_relative "../support/events_examples.rb"
+
+DATA_PATH = "/data/.postcodes"
+
+describe Firstclasspostcodes::Client do
+  subject { Firstclasspostcodes::Client.new }
+
+  let(:fixtures) { subject.request(method: :get, path: DATA_PATH) }
+
+  let(:fixture) { fixtures.sample }
+
+  describe "#get_postcode" do
+    it "retrieves the postcode correctly" do
+      response = subject.get_postcode(fixture[:postcode])
+      expect(response[:postcode]).to eq(fixture[:postcode])
+    end
+  end
+
+  describe "#get_lookup" do
+    it "retrieves postcodes by geolocation correctly" do
+      response = subject.get_lookup(fixture)
+      expect(response[0][:postcode]).to eq(fixture[:postcode])
+    end
+  end
+end

data/spec/firstclasspostcodes_spec.rb

@@ -95,9 +95,9 @@ describe Firstclasspostcodes do
     let(:config) { Firstclasspostcodes::Configuration.new }
 
     it "defaults to 0" do
-      expect(Firstclasspostcodes::Configuration.default.timeout).to eq(0)
-      expect(config.timeout).to eq(0)
-      expect(config.to_request_params[:timeout]).to eq(0)
+      expect(Firstclasspostcodes::Configuration.default.timeout).to eq(30)
+      expect(config.timeout).to eq(30)
+      expect(config.to_request_params[:timeout]).to eq(30)
     end
 
     it "can be customized" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: firstclasspostcodes
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Firstclasspostcodes
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-01-18 00:00:00.000000000 Z
+date: 2020-01-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -61,12 +61,14 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".dependabot/config.yml"
+- ".github/images/cover.png"
 - ".github/workflows/gem.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
 - Gemfile
 - LICENSE
+- README.md
 - Rakefile
 - firstclasspostcodes.gemspec
 - lib/firstclasspostcodes.rb
@@ -82,6 +84,7 @@ files:
 - lib/firstclasspostcodes/version.rb
 - spec/firstclasspostcodes/client_spec.rb
 - spec/firstclasspostcodes/events_spec.rb
+- spec/firstclasspostcodes/integration_spec.rb
 - spec/firstclasspostcodes/operations/get_lookup_spec.rb
 - spec/firstclasspostcodes/operations/get_postcode_spec.rb
 - spec/firstclasspostcodes/operations/methods/format_address_spec.rb