aus_post_api 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d5236689702f486d8307a74b0b01ca9c0b8b7733
+  data.tar.gz: aec946ad8ea44c0ea0358b819470328c658ec7dc
+SHA512:
+  metadata.gz: 4aa3123f0a1231cb164673ca8d32f9a4c133f2fbe36669ac0ef4466391a9095957f87447485ff3e6c29cc71ef41bfab27ca5c869e179cf7272fa57c7814f6d77
+  data.tar.gz: df27ce56b45e696c99a44bfe78b8e0aab0d16b1d9ab24d08424d7e10885aedc91f94b88a78793658902fc23274df41ea13c86165e73f65e374fb959381b06990

data/.gitignore

@@ -0,0 +1,2 @@
+spec/fixtures/**/*.*
+aus_post_api*.gem

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+gem 'rspec'
+gem 'vcr'
+gem 'webmock'
+gem 'rake'
+gem 'require_all'

data/Gemfile.lock

@@ -0,0 +1,37 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.3.8)
+    crack (0.4.2)
+      safe_yaml (~> 1.0.0)
+    diff-lcs (1.2.5)
+    rake (10.4.2)
+    require_all (1.3.2)
+    rspec (3.2.0)
+      rspec-core (~> 3.2.0)
+      rspec-expectations (~> 3.2.0)
+      rspec-mocks (~> 3.2.0)
+    rspec-core (3.2.3)
+      rspec-support (~> 3.2.0)
+    rspec-expectations (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-mocks (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-support (3.2.2)
+    safe_yaml (1.0.4)
+    vcr (2.9.3)
+    webmock (1.21.0)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake
+  require_all
+  rspec
+  vcr
+  webmock

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Jared Shay
+
+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/README.md

@@ -0,0 +1,147 @@
+# AusPostAPI
+
+The AusPostAPI gem is a wrapper around the Australia Post Developer API. Currently only the Postage Assesment Calculator (PAC) API is implemented.
+
+## Documentation
+
+Full and up to date documentation can be found at https://developers.auspost.com.au/apis
+
+*see below for full list of endpoints that can be called from this gem*
+
+## Usage
+
+### Ruby
+
+```ruby
+AusPostAPI::PAC.new(config).endpoint(params)
+```
+
+### Rails
+
+```ruby
+# config/initializers/aus_post_api.rb
+
+$aus_post_api = AusPostAPI::PAC.new(config)
+
+# app/some_file.rb
+
+$aus_post_api.endpoint(params)
+```
+
+## Configuration
+The gem requires a `FORMAT` of either `'json'` or `'xml'`, and the `PAC_AUTH_KEY` to be set. You can get an auth key at https://developers.auspost.com.au/sign-up-for-an-API-key
+
+```ruby
+{
+  FORMAT: 'xml',
+  PAC_API_KEY: 123-456
+}
+```
+
+## Endpoints
+
+There are no validations on any parameters. Consult the Australia Post documentation for what units and limitations apply.
+
+```
+domestic_postcode_search
+  Required Attributes:
+    - q
+  Optional Attributes:
+    - state
+    - excludepostboxflag
+
+country
+
+domestic_letter_thickness
+
+domestic_letter_weight
+
+domestic_letter_size
+
+international_letter_weight
+
+international_parcel_weight
+
+domestic_parcel_weight
+
+domestic_parcel_type
+
+domestic_parcel_size
+
+postage_letter_domestic_service
+  Required Attributes:
+    - length
+    - width
+    - thickness
+    - weight
+
+postage_parcel_domestic_service
+  Required Attributes:
+    - from_postcode
+    - to_postcode
+    - length
+    - width
+    - height
+    - weight
+
+postage_letter_international_service
+  Required Attributes:
+    - country_code
+    - weight
+
+postage_parcel_international_service
+  Required Attributes:
+    - country_code
+    - weight
+
+postage_parcel_domestic_calculate
+  Required Attributes:
+    - from_postcode
+    - to_postcode
+    - length
+    - width
+    - height
+    - weight
+    - service_code
+  Optional Attributes:
+    - option_code
+    - suboption_code
+    - extra_cover
+
+postage_parcel_international_calculate
+  Required Attributes:
+    - country_code
+    - weight
+    - service_code
+  Optional Attributes:
+    - option_code
+    - suboption_code
+    - extra_cover
+
+postage_letter_domestic_calculate
+  Required Attributes:
+    - service_code
+    - weight
+  Optional Attributes:
+    - option_code
+    - suboption_code
+    - extra_cover
+
+postage_letter_international_calculate
+  Required Attributes:
+    - country_code
+    - service_code
+  Optional Attributes:
+    - weight
+    - option_code
+    - suboption_code
+    - extra_cover
+```
+
+## Testing
+Set the config `TEST: true` for use in testing environments. This will use the Australia Post testing endpoint, and ignore any api keys provided.
+
+*note: at the time of writing this the testing endpoint is unreliable. Consider getting additional api keys for testing purposes and not setting the TEST parameter in your tests*
+
+## Contributing
+Fork and PR!

data/Rakefile

@@ -0,0 +1,32 @@
+desc "Open an irb session preloaded with the aus_post gem"
+task :console do
+  sh "irb -I lib -r aus_post_api.rb"
+end
+
+desc "Display all PAC endpoints with a list of required values"
+task :pac_docs do
+  require_relative 'lib/aus_post_api'
+
+
+  docs = ""
+  (AusPostAPI::PAC.instance_methods - Object.instance_methods).each do |method|
+      klass = "AusPostAPI::PAC::#{method.to_s.split("_").map(&:capitalize).join}"
+      required = Kernel.const_get(klass).required_attributes
+      optional = Kernel.const_get(klass).optional_attributes
+
+      docs << method.to_s
+      docs << "\n"
+
+      if !required.empty?
+        docs << "  Required Attributes:\n"
+        required.each { |attr| docs << "    - #{attr}\n"}
+      end
+      if !optional.empty?
+        docs << "  Optional Attributes:\n"
+        optional.each { |attr| docs << "    - #{attr}\n"}
+      end
+      docs << "\n"
+  end
+
+  puts docs.chomp!
+end

data/aus_post_api.gemspec

@@ -0,0 +1,14 @@
+Gem::Specification.new do |gem|
+  gem.authors       = ["JaredShay"]
+  gem.email         = ["jared.shay@gmail.com"]
+  gem.description   = %q{Wrapper for Australia Post's developer API}
+  gem.summary       = %q{Wrapper for Australia Post's developer API}
+  gem.homepage      = "https://github.com/jaredshay/aus_post_api"
+
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- spec/*`.split("\n")
+  gem.name          = "aus_post_api"
+  gem.require_paths = ["lib"]
+  gem.version       = '1.0.0'
+  gem.license       = "MIT"
+end

data/lib/aus_post_api.rb

@@ -0,0 +1,7 @@
+require 'require_all'
+
+require_all 'lib'
+
+# The AusPostAPI module is the top level name space for the gem.
+module AusPostAPI
+end

data/lib/aus_post_api/dce.rb

@@ -0,0 +1,15 @@
+module AusPostAPI
+  # The PAC class implements methods specified by the Australia Post Delivery
+  # Choices API. A config hash must be supplied that specifies a valid
+  # DCE_AUTH_KEY, and request format. Setting the key TEST to true in the config
+  # hash will ignore any supplied auth_key and use the test endpoint.
+  class DCE
+    def initialize(config)
+      @config = config
+    end
+
+    def validate_australian_address(params = {})
+      AusPostAPI::DCE::ValidateAustralianAddress.new(params, @config).execute
+    end
+  end
+end

data/lib/aus_post_api/dce/endpoint.rb

@@ -0,0 +1,80 @@
+require 'base64'
+
+module AusPostAPI
+  class DCE
+    # Abstract class that defines a DCE::Endpoint. It implements the `uri` &
+    # `headers` methods and expects the `api_uri` method to be implemented.
+    class Endpoint < AusPostAPI::Endpoint
+      LIVE_URI = 'https://api.auspost.com.au/'
+      FORMATS  = ['json', 'xml']
+
+      def uri
+        "#{LIVE_URI}/#{api_uri}.#{format}?#{params}"
+      end
+
+      def headers
+        { "Authorization" => "Basic #{basic_auth}" }
+      end
+
+      private
+
+      def api_uri
+        raise ImplementationError.new('api_uri')
+      end
+
+      def format
+        if @config[:FORMAT].nil?
+          raise NoFormatProvidedError
+        else
+          if !FORMATS.include?(@config[:FORMAT])
+            raise InvalidFormatError
+          else
+            @config[:FORMAT]
+          end
+        end
+      end
+
+      def params
+        [].tap { |result|
+          @attributes.keys.each { |a| result << "#{a}=#{self.send(a).split.join('+')}" }
+        }.join('&')
+      end
+
+      def basic_auth
+        Base64.encode64("#{username}:#{password}")
+      end
+
+      def username
+        raise NoHeaderProvidedError.new('USERNAME') if @config[:USERNAME].nil?
+
+        @config[:USERNAME]
+      end
+
+      def password
+        raise NoHeaderProvidedError.new('PASSWORD') if @config[:PASSWORD].nil?
+
+        @config[:PASSWORD]
+      end
+
+      class NoHeaderProvidedError < StandardError
+        def initialize(header)
+          super("The called endpoint requires the #{header} config to be set")
+        end
+      end
+
+      class InvalidFormatError < StandardError
+        def initialize
+          super("Accepted formats are: #{AusPostAPI::DCE::Endpoint::FORMATS.join(', ')}")
+        end
+      end
+
+      class NoFormatProvidedError < InvalidFormatError; end
+
+      class ImplementationError < StandardError
+        def initialize(method)
+          super("No #{method} implemented")
+        end
+      end
+    end
+  end
+end

data/lib/aus_post_api/dce/validate_australian_address.rb

@@ -0,0 +1,12 @@
+module AusPostAPI
+  class DCE
+    class ValidateAustralianAddress < AusPostAPI::DCE::Endpoint
+      required_attributes :addressline1, :suburb, :postcode, :state, :country
+      optional_attributes :addressline2
+
+      def api_uri
+        "ValidateAddress"
+      end
+    end
+  end
+end

data/lib/aus_post_api/endpoint.rb

@@ -0,0 +1,66 @@
+require_relative "./endpoint/attributes"
+
+# The Endpoint class is an abstract class that sets attributes and handles the
+# execution of API endoint calls.
+#
+# It requires two instance methods to be defined.
+#    * `uri` - returns a valid uri string that represents the full api path
+#    * `headers` - returns a hash of key value pairs for the request
+#
+# The attributes module adds class level methods for specifying the attributes
+# of the API call.
+#    * `required_attributes`
+#    * `optional_attributes`
+module AusPostAPI
+  class Endpoint
+    include AusPostAPI::Endpoint::Attributes
+
+    def initialize(attributes, config, uri_handler = AusPostAPI::UriHandler)
+      @config      = config
+      @attributes  = attributes
+      @uri_handler = uri_handler
+
+      set_attributes
+    end
+
+    def execute
+      @uri_handler.call(uri, headers)
+    end
+
+    private
+
+    def uri
+      raise ImplementationError.new("uri")
+    end
+
+    def headers
+      raise ImplementationError.new("headers")
+    end
+
+    def set_attributes
+      required_param = -> (attr) { raise RequiredArgumentError.new(attr) }
+
+      required_attributes.each do |attr|
+        self.send("#{attr}=", @attributes.fetch(attr, &required_param))
+      end
+
+      optional_attributes.each do |attr|
+        if @attributes.has_key?(attr)
+          self.send("#{attr}=", @attributes.fetch(attr))
+        end
+      end
+    end
+
+    class RequiredArgumentError < StandardError
+      def initialize(attr)
+        super("#{attr} is a required argument")
+      end
+    end
+
+    class ImplementationError < StandardError
+      def initialize(method)
+        super("No #{method} implemented")
+      end
+    end
+  end
+end