friendly_shipping 0.2.6 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6848c5420a248cc3b6a382549bbe8833a73cf69a
-  data.tar.gz: 7b935b92f55ef273aaf771114a1009e58920a024
+  metadata.gz: 821bec044ee86ff1e468dd392ae55c475510af6c
+  data.tar.gz: 153b7226c2e01afe5b6d7fdc260e39b712986ae5
 SHA512:
-  metadata.gz: 778355fb23316ce44d5cdb84e158efce2c2f7f44281677a995df50a47853f2efe92154d8b956c747c24cbd074b70d06e096384afb50a61572537fb53a3dee480
-  data.tar.gz: dc0dc9ef40db1f14d5a81a08189bf594e476af2b7c8d69eb2cc9ed0b7d93fc68cef1e7d8c60e4fbd64a559e48aa53afec98ba36247ff37adca9ebfb38cf8b35b
+  metadata.gz: a1ad8abee5b1a56f33cc8c5b8a4d55d4bce1f056e74a0719ea237ab577587921b43ada0ca50f35ab52bba261b2fc18598e612a82185a9d172c3d45918cf07f8e
+  data.tar.gz: 29a07b0165a570d6cbf5c008e2ff1a67aa6ce2e245be10357cbaaeb13b88c888e74419dec65ca9df7ce147e38524eb1b42a55393dba6f17c8cf2d2e4cef61338

data/README.md

@@ -1,8 +1,6 @@
-# FriendlyShipping
+# FriendlyShipping - the friendly shipping provider API wrapper
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/friendly_shipping`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+This gem provides wrappers for popular shipping provider APIs. Currently, there are implementations for rate quoting and address validation, as well as shipping label generation via the `ShipStation` API.
 
 ## Installation
 
@@ -22,7 +20,74 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+The entry point for using FriendlyShipping are the `service` objects that each represent an API provider. Currently, there are three services:
+
+1. `FriendlyShipping::Services::Ups`
+2. `FriendlyShipping::Services::Usps`
+3. `FriendlyShipping::Services::ShipEngine`
+
+The services are instantiated with the credentials they need as well as a `test` flag to indicate whether to use their respective `sandbox` environments.
+
+The individual API endpoints can be reached through the public methods of the respective service objects, such as `#rate_estimates`, `#labels`, or `#address_validation`. This gem makes heavy use of classes from the [`physical` gem](https://github.com/friendlycart/physical) to represent the physical world (shipments, packages, addresses, and items).
+
+### Return values
+
+All calls to `FriendlyShipping` will return a `Dry::Monads::Result` instance, so either a `Success` or `Failure`. Wrapped inside this monad is a `FriendlyShipping::ApiResult` (in the success case) or a `FriendlyShipping::ApiFailure` object that contains the desired data under `#data` `ApiResult` and `ApiFailure` also contain the original request generated by this gem and the response returned by the respective service.
+
+### Supported Services
+
+#### ShipEngine
+
+The service class for ShipEngine is `FriendlyShipping::Services::ShipEngine`. Initialize like so:
+
+```rb
+service = FriendlyShipping::Services::ShipEngine.new(token: ENV['SHIPENGINE_TOKEN'], test: true)
+```
+
+The following methods are supported:
+
+- `#carriers` - List all configured carriers
+- `#rate_estimates(physical_shipment, carriers: [friendly_shipping_carrier])` - Get rate estimates for a shipment
+- `#labels(physical_shipment)` - Get labels for a shipments. Currently only supports USPS labels, other services are untested. The API of this method is still subject to change.
+- `#void(physical_label)` - Void a label and get the cost refunded
+
+#### UPS (United Parcel Service)
+
+The service class for UPS is `FriendlyShipping::Services::Ups`. Initialize like so:
+
+```rb
+service = FriendlyShipping::Services::Ups.new(
+  key: ENV['UPS_API_KEY'],
+  login: ENV['UPS_API_LOGIN'],
+  password: ENV['UPS_API_PASSWORD'],
+  test: true
+)
+```
+
+The following methods are supported:
+
+- `#carriers` - List all configured carriers (always returns UPS)
+- `#rate_estimates(physical_shipment)` - Get rate estimates for a shipment
+- `#address_validation(physical_location)` - Perform a detailed address validation and determine whether an address is commercial or residential.
+- `#city_state_lookup(physical_location)` - Lookup City and State for a given ZIP code.
+
+#### USPS (United States Postal Service)
+
+The service class for USPS is `FriendlyShipping::Services::Usps`. Initialize like so:
+
+```rb
+service = FriendlyShipping::Services::Usps.new(
+  login: ENV['USPS_API_LOGIN'],
+  test: true
+)
+```
+
+The following methods are supported:
+
+- `#carriers` - List all configured carriers (always returns USPS)
+- `#rate_estimates(physical_shipment)` - Get rate estimates for a shipment
+- `#address_validation(physical_location)` - Perform a detailed address validation and determine whether an address is commercial or residential.
+- `#city_state_lookup(physical_location)` - Lookup City and State for a given ZIP code.
 
 ## Development
 
@@ -32,7 +97,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/friendly_shipping. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/friendlycart/friendly_shipping. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 
@@ -40,4 +105,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the FriendlyShipping project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/friendly_shipping/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the FriendlyShipping project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/friendlycart/friendly_shipping/blob/master/CODE_OF_CONDUCT.md).

data/lib/friendly_shipping.rb

@@ -9,6 +9,8 @@ require "friendly_shipping/carrier"
 require "friendly_shipping/shipping_method"
 require "friendly_shipping/label"
 require "friendly_shipping/rate"
+require "friendly_shipping/api_result"
+require "friendly_shipping/api_failure"
 
 require "friendly_shipping/services/ship_engine"
 require "friendly_shipping/services/ups"

data/lib/friendly_shipping/api_failure.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  class ApiFailure
+    attr_reader :failure, :original_request, :original_response
+
+    def initialize(failure, original_request:, original_response:)
+      @failure = failure
+
+      # We do not want to attach debugging information in every single response to save memory in production
+      return unless original_request&.debug
+
+      @original_request = original_request
+      @original_response = original_response
+    end
+
+    def to_s
+      failure.to_s
+    end
+  end
+end

data/lib/friendly_shipping/api_result.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  class ApiResult
+    attr_reader :data, :original_request, :original_response
+
+    def initialize(data, original_request: nil, original_response: nil)
+      @data = data
+
+      # We do not want to attach debugging information in every single response to save memory in production
+      return unless original_request&.debug
+
+      @original_request = original_request
+      @original_response = original_response
+    end
+  end
+end

data/lib/friendly_shipping/request.rb

@@ -2,12 +2,13 @@
 
 module FriendlyShipping
   class Request
-    attr_reader :url, :body, :headers
+    attr_reader :url, :body, :headers, :debug
 
-    def initialize(url:, body: nil, headers: {})
+    def initialize(url:, body: nil, headers: {}, debug: false)
       @url = url
       @body = body
       @headers = headers
+      @debug = debug
     end
   end
 end

data/lib/friendly_shipping/services/ship_engine.rb

@@ -24,27 +24,49 @@ module FriendlyShipping
         @client = client
       end
 
+      # Get configured carriers from USPS
+      #
+      # @return [Result<ApiResult<Array<Carrier>>>] Carriers configured in your shipstation account
       def carriers
         request = FriendlyShipping::Request.new(
           url: API_BASE + API_PATHS[:carriers],
           headers: request_headers
         )
         client.get(request).fmap do |response|
-          ParseCarrierResponse.new(response: response).call
+          ParseCarrierResponse.call(request: request, response: response)
         end
       end
 
-      def rate_estimates(shipment, carriers)
+      # Get rate estimates from ShipEngine
+      #
+      # @param [Physical::Shipment] shipment The shipment object we're trying to get results for
+      #
+      # @options[:carriers] [Physical::Carrier] The carriers we want to get rates from. What counts
+      # here is the carrier code, so by specifying them upfront you can save a request.
+      #
+      # @return [Result<ApiResult<Array<FriendlyShipping::Rate>>>] When successfully parsing, an array of rates in a Success Monad.
+      #   When the parsing is not successful or ShipEngine can't give us rates, a Failure monad containing something that
+      #   can be serialized into an error message using `to_s`.
+      def rate_estimates(shipment, options = {})
+        selected_carriers = options[:carriers] || carriers.value!.data
         request = FriendlyShipping::Request.new(
           url: API_BASE + 'rates/estimate',
-          body: SerializeRateEstimateRequest.call(shipment: shipment, carriers: carriers).to_json,
+          body: SerializeRateEstimateRequest.call(shipment: shipment, carriers: selected_carriers).to_json,
           headers: request_headers
         )
-        client.post(request).fmap do |response|
-          ParseRateEstimateResponse.call(response: response, request: request, carriers: carriers)
+        client.post(request).bind do |response|
+          ParseRateEstimateResponse.call(response: response, request: request, carriers: selected_carriers)
         end
       end
 
+      # Get label(s) from ShipEngine
+      #
+      # @param [Physical::Shipment] shipment The shipment object we're trying to get labels for
+      #   Note: Some ShipEngine carriers, notably USPS, only support one package per shipment, and that's
+      #   all that the integration supports at this point.
+      #
+      # @return [Result<ApiResult<Array<FriendlyShipping::Label>>>] The label returned.
+      #
       def labels(shipment)
         request = FriendlyShipping::Request.new(
           url: API_BASE + API_PATHS[:labels],
@@ -63,7 +85,7 @@ module FriendlyShipping
           headers: request_headers
         )
         client.put(request).bind do |response|
-          ParseVoidResponse.new(response: response).call
+          ParseVoidResponse.call(request: request, response: response)
         end
       end
 

data/lib/friendly_shipping/services/ship_engine/parse_carrier_response.rb

@@ -6,41 +6,45 @@ module FriendlyShipping
   module Services
     class ShipEngine
       class ParseCarrierResponse
-        def initialize(response:)
-          @response = response
-        end
+        class << self
+          def call(request:, response:)
+            parsed_json = JSON.parse(response.body)
+            carriers = parsed_json['carriers'].map do |carrier_data|
+              carrier = FriendlyShipping::Carrier.new(
+                id: carrier_data['carrier_id'],
+                name: carrier_data['friendly_name'],
+                code: carrier_data['carrier_code'],
+                balance: carrier_data['balance'],
+                data: carrier_data
+              )
 
-        def call
-          parsed_json = JSON.parse(@response.body)
-          parsed_json['carriers'].map do |carrier_data|
-            carrier = FriendlyShipping::Carrier.new(
-              id: carrier_data['carrier_id'],
-              name: carrier_data['friendly_name'],
-              code: carrier_data['carrier_code'],
-              balance: carrier_data['balance'],
-              data: carrier_data
-            )
+              carrier_data['services'].each do |method_hash|
+                shipping_method = parse_shipping_method(carrier, method_hash)
+                carrier.shipping_methods << shipping_method
+              end
 
-            carrier_data['services'].each do |method_hash|
-              shipping_method = parse_shipping_method(carrier, method_hash)
-              carrier.shipping_methods << shipping_method
+              carrier
             end
 
-            carrier
+            ApiResult.new(
+              carriers,
+              original_request: request,
+              original_response: response
+            )
           end
-        end
 
-        private
+          private
 
-        def parse_shipping_method(carrier, shipping_method_data)
-          FriendlyShipping::ShippingMethod.new(
-            carrier: carrier,
-            name: shipping_method_data["name"],
-            service_code: shipping_method_data["service_code"],
-            domestic: shipping_method_data["domestic"],
-            international: shipping_method_data["international"],
-            multi_package: shipping_method_data["is_multi_package_supported"]
-          )
+          def parse_shipping_method(carrier, shipping_method_data)
+            FriendlyShipping::ShippingMethod.new(
+              carrier: carrier,
+              name: shipping_method_data["name"],
+              service_code: shipping_method_data["service_code"],
+              domestic: shipping_method_data["domestic"],
+              international: shipping_method_data["international"],
+              multi_package: shipping_method_data["is_multi_package_supported"]
+            )
+          end
         end
       end
     end

data/lib/friendly_shipping/services/ship_engine/parse_label_response.rb

@@ -9,6 +9,7 @@ module FriendlyShipping
       class ParseLabelResponse
         def self.call(request:, response:)
           parsed_json = JSON.parse(response.body)
+
           label_uri_string = parsed_json['label_download']['href']
           label_data = nil
           label_url = nil
@@ -17,21 +18,20 @@ module FriendlyShipping
           else
             label_url = label_uri_string
           end
-          [
-            FriendlyShipping::Label.new(
-              id: parsed_json['label_id'],
-              shipment_id: parsed_json['shipment_id'],
-              tracking_number: parsed_json['tracking_number'],
-              service_code: parsed_json['service_code'],
-              label_href: label_url,
-              label_data: label_data,
-              label_format: parsed_json['label_format'].to_sym,
-              shipment_cost: parsed_json['shipment_cost']['amount'],
-              data: parsed_json,
-              original_request: request,
-              original_response: response
-            )
-          ]
+
+          label = FriendlyShipping::Label.new(
+            id: parsed_json['label_id'],
+            shipment_id: parsed_json['shipment_id'],
+            tracking_number: parsed_json['tracking_number'],
+            service_code: parsed_json['service_code'],
+            label_href: label_url,
+            label_data: label_data,
+            label_format: parsed_json['label_format'].to_sym,
+            shipment_cost: parsed_json['shipment_cost']['amount'],
+            data: parsed_json
+          )
+
+          ApiResult.new([label], original_request: request, original_response: response)
         end
       end
     end

data/lib/friendly_shipping/services/ship_engine/parse_rate_estimate_response.rb

@@ -7,10 +7,12 @@ module FriendlyShipping
   module Services
     class ShipEngine
       class ParseRateEstimateResponse
+        extend Dry::Monads::Result::Mixin
+
         class << self
           def call(response:, carriers:, request:)
             parsed_json = JSON.parse(response.body)
-            parsed_json.map do |rate|
+            rates = parsed_json.map do |rate|
               carrier = carriers.detect { |c| c.id == rate['carrier_id'] }
               next unless carrier
 
@@ -29,6 +31,14 @@ module FriendlyShipping
                 original_response: response
               )
             end.compact
+
+            Success(
+              ApiResult.new(
+                rates,
+                original_request: request,
+                original_response: response
+              )
+            )
           end
 
           private

data/lib/friendly_shipping/services/ship_engine/parse_void_response.rb

@@ -6,18 +6,20 @@ module FriendlyShipping
   module Services
     class ShipEngine
       class ParseVoidResponse
-        include Dry::Monads::Result::Mixin
+        extend Dry::Monads::Result::Mixin
 
-        attr_reader :response
-
-        def initialize(response:)
-          @response = response
-        end
-
-        def call
+        def self.call(request:, response:)
           parsed_json = JSON.parse(response.body)
           approved, message = parsed_json["approved"], parsed_json["message"]
-          approved ? Success(message) : Failure(message)
+          if approved
+            Success(
+              ApiResult.new(message, original_request: request, original_response: response)
+            )
+          else
+            Failure(
+              ApiFailure.new(message, original_request: request, original_response: response)
+            )
+          end
         end
       end
     end

data/lib/friendly_shipping/services/ups.rb

@@ -3,7 +3,11 @@
 require 'dry/monads/result'
 require 'friendly_shipping/services/ups/client'
 require 'friendly_shipping/services/ups/serialize_access_request'
+require 'friendly_shipping/services/ups/serialize_city_state_lookup_request'
+require 'friendly_shipping/services/ups/serialize_address_validation_request'
 require 'friendly_shipping/services/ups/serialize_rating_service_selection_request'
+require 'friendly_shipping/services/ups/parse_address_validation_response'
+require 'friendly_shipping/services/ups/parse_city_state_lookup_response'
 require 'friendly_shipping/services/ups/parse_rate_response'
 require 'friendly_shipping/services/ups/shipping_methods'
 
@@ -25,6 +29,8 @@ module FriendlyShipping
       LIVE_URL = 'https://onlinetools.ups.com'
 
       RESOURCES = {
+        address_validation: '/ups.app/xml/XAV',
+        city_state_lookup: '/ups.app/xml/AV',
         rates: '/ups.app/xml/Rate'
       }.freeze
 
@@ -40,7 +46,11 @@ module FriendlyShipping
         Success([CARRIER])
       end
 
-      def rate_estimates(shipment, _carriers)
+      # Get rates for a shipment
+      # @param [Physical::Shipment] location The shipment we want to get rates for
+      # @return [Result<ApiResult<Array<Rate>>>] The rates returned from UPS encoded in a
+      #   `FriendlyShipping::ApiResult` object.
+      def rate_estimates(shipment, _options = {})
         rate_request_xml = SerializeRatingServiceSelectionRequest.call(shipment: shipment)
         url = base_url + RESOURCES[:rates]
         request = FriendlyShipping::Request.new(
@@ -53,6 +63,42 @@ module FriendlyShipping
         end
       end
 
+      # Validate an address.
+      # @param [Physical::Location] location The address we want to verify
+      # @return [Result<ApiResult<Array<Physical::Location>>>] The response data from UPS encoded in a
+      #   `Physical::Location` object. Name and Company name are always nil, the
+      #   address lines will be made conformant to what UPS considers right. The returned location will
+      #   have the address_type set if possible.
+      def address_validation(location)
+        address_validation_request_xml = SerializeAddressValidationRequest.call(location: location)
+        url = base_url + RESOURCES[:address_validation]
+        request = FriendlyShipping::Request.new(
+          url: url,
+          body: access_request_xml + address_validation_request_xml
+        )
+
+        client.post(request).bind do |response|
+          ParseAddressValidationResponse.call(response: response, request: request)
+        end
+      end
+
+      # Find city and state for a given ZIP code
+      # @param [Physical::Location] location A location object with country and ZIP code set
+      # @return [Result<ApiResult<Array<Physical::Location>>>] The response data from UPS encoded in a
+      #   `Physical::Location` object. Country, City and ZIP code will be set, everything else nil.
+      def city_state_lookup(location)
+        city_state_lookup_request_xml = SerializeCityStateLookupRequest.call(location: location)
+        url = base_url + RESOURCES[:city_state_lookup]
+        request = FriendlyShipping::Request.new(
+          url: url,
+          body: access_request_xml + city_state_lookup_request_xml
+        )
+
+        client.post(request).bind do |response|
+          ParseCityStateLookupResponse.call(response: response, request: request, location: location)
+        end
+      end
+
       private
 
       def access_request_xml

data/lib/friendly_shipping/services/ups/parse_address_validation_response.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class Ups
+      class ParseAddressValidationResponse
+        extend Dry::Monads::Result::Mixin
+
+        def self.call(request:, response:)
+          parsing_result = ParseXMLResponse.call(response.body, 'AddressValidationResponse')
+
+          parsing_result.bind do |xml|
+            if xml.at('NoCandidatesIndicator')
+              Failure(
+                FriendlyShipping::ApiFailure.new(
+                  'Address is probably invalid. No similar valid addresses found.',
+                  original_request: request,
+                  original_response: response
+                )
+              )
+            else
+              Success(
+                FriendlyShipping::ApiResult.new(
+                  build_suggestions(xml),
+                  original_request: request,
+                  original_response: response
+                )
+              )
+            end
+          end
+        end
+
+        def self.build_suggestions(xml)
+          xml.xpath('//AddressKeyFormat').map do |address_fragment|
+            Physical::Location.new(
+              address1: address_fragment.xpath('AddressLine[1]')[0]&.text,
+              address2: address_fragment.xpath('AddressLine[2]')[0]&.text,
+              company_name: address_fragment.at('ConsigneeName')&.text,
+              city: address_fragment.at('PoliticalDivision2')&.text,
+              region: address_fragment.at('PoliticalDivision1')&.text,
+              country: address_fragment.at('CountryCode')&.text,
+              zip: "#{address_fragment.at('PostcodePrimaryLow')&.text}-#{address_fragment.at('PostcodeExtendedLow')&.text}",
+              address_type: address_fragment.at('AddressClassification/Description')&.text&.downcase
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ups/parse_city_state_lookup_response.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class Ups
+      class ParseCityStateLookupResponse
+        extend Dry::Monads::Result::Mixin
+
+        def self.call(request:, response:, location:)
+          parsing_result = ParseXMLResponse.call(response.body, 'AddressValidationResponse')
+
+          parsing_result.fmap do |xml|
+            FriendlyShipping::ApiResult.new(
+              [
+                Physical::Location.new(
+                  city: xml.at('AddressValidationResult/Address/City')&.text,
+                  region: xml.at('AddressValidationResult/Address/StateProvinceCode')&.text,
+                  country: location.country,
+                  zip: xml.at('AddressValidationResult/Address/PostcodePrimaryLow')&.text,
+                )
+              ],
+              original_request: request,
+              original_response: response
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ups/parse_rate_response.rb

@@ -9,33 +9,39 @@ module FriendlyShipping
         def self.call(request:, response:, shipment:)
           parsing_result = ParseXMLResponse.call(response.body, 'RatingServiceSelectionResponse')
           parsing_result.fmap do |xml|
-            xml.root.css('> RatedShipment').map do |rated_shipment|
-              service_code = rated_shipment.at('Service/Code').text
-              shipping_method = CARRIER.shipping_methods.detect do |sm|
-                sm.service_code == service_code && shipment.origin.country.in?(sm.origin_countries)
-              end
-              days_to_delivery = rated_shipment.at('GuaranteedDaysToDelivery').text.to_i
-              currency = Money::Currency.new(rated_shipment.at('TotalCharges/CurrencyCode').text)
-              total_cents = rated_shipment.at('TotalCharges/MonetaryValue').text.to_d * currency.subunit_to_unit
-              insurance_price = rated_shipment.at('ServiceOptionsCharges/MonetaryValue').text.to_f
-              negotiated_rate = rated_shipment.at(
-                'NegotiatedRates/NetSummaryCharges/GrandTotal/MonetaryValue'
-              )&.text.to_f
+            FriendlyShipping::ApiResult.new(
+              build_rates(xml, shipment),
+              original_request: request,
+              original_response: response
+            )
+          end
+        end
 
-              FriendlyShipping::Rate.new(
-                shipping_method: shipping_method,
-                amounts: { total: Money.new(total_cents, currency) },
-                warnings: [rated_shipment.at("RatedShipmentWarning")&.text].compact,
-                errors: [],
-                data: {
-                  insurance_price: insurance_price,
-                  negotiated_rate: negotiated_rate,
-                  days_to_delivery: days_to_delivery
-                },
-                original_request: request,
-                original_response: response
-              )
+        def self.build_rates(xml, shipment)
+          xml.root.css('> RatedShipment').map do |rated_shipment|
+            service_code = rated_shipment.at('Service/Code').text
+            shipping_method = CARRIER.shipping_methods.detect do |sm|
+              sm.service_code == service_code && shipment.origin.country.in?(sm.origin_countries)
             end
+            days_to_delivery = rated_shipment.at('GuaranteedDaysToDelivery').text.to_i
+            currency = Money::Currency.new(rated_shipment.at('TotalCharges/CurrencyCode').text)
+            total_cents = rated_shipment.at('TotalCharges/MonetaryValue').text.to_d * currency.subunit_to_unit
+            insurance_price = rated_shipment.at('ServiceOptionsCharges/MonetaryValue').text.to_f
+            negotiated_rate = rated_shipment.at(
+              'NegotiatedRates/NetSummaryCharges/GrandTotal/MonetaryValue'
+            )&.text.to_f
+
+            FriendlyShipping::Rate.new(
+              shipping_method: shipping_method,
+              amounts: { total: Money.new(total_cents, currency) },
+              warnings: [rated_shipment.at("RatedShipmentWarning")&.text].compact,
+              errors: [],
+              data: {
+                insurance_price: insurance_price,
+                negotiated_rate: negotiated_rate,
+                days_to_delivery: days_to_delivery
+              }
+            )
           end
         end
       end

data/lib/friendly_shipping/services/ups/serialize_address_validation_request.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class Ups
+      class SerializeAddressValidationRequest
+        attr_reader :location
+
+        REQUEST_ACTION = 'XAV'
+        REQUEST_OPTIONS = {
+          validation: 1,
+          classification: 2,
+          both: 3
+        }.freeze
+
+        def self.call(location:)
+          xml_builder = Nokogiri::XML::Builder.new do |xml|
+            xml.AddressValidationRequest do
+              xml.Request do
+                xml.RequestAction REQUEST_ACTION
+                xml.RequestOption REQUEST_OPTIONS[:both]
+              end
+
+              xml.AddressKeyFormat do
+                xml.AddressLine location.address1
+                xml.AddressLine location.address2
+                xml.PoliticalDivision2 location.city
+                xml.PoliticalDivision1 location.region.code
+                xml.PostcodePrimaryLow location.zip
+                xml.CountryCode location.country.code
+              end
+            end
+          end
+          xml_builder.to_xml
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ups/serialize_city_state_lookup_request.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class Ups
+      class SerializeCityStateLookupRequest
+        REQUEST_ACTION = 'AV'
+
+        def self.call(location:)
+          xml_builder = Nokogiri::XML::Builder.new do |xml|
+            xml.AddressValidationRequest do
+              xml.Request do
+                xml.RequestAction REQUEST_ACTION
+              end
+              xml.Address do
+                xml.PostalCode location.zip
+                xml.CountryCode location.country.code
+              end
+            end
+          end
+          xml_builder.to_xml
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/usps.rb

@@ -2,7 +2,11 @@
 
 require 'friendly_shipping/services/usps/client'
 require 'friendly_shipping/services/usps/shipping_methods'
+require 'friendly_shipping/services/usps/serialize_address_validation_request'
+require 'friendly_shipping/services/usps/serialize_city_state_lookup_request'
 require 'friendly_shipping/services/usps/serialize_rate_request'
+require 'friendly_shipping/services/usps/parse_address_validation_response'
+require 'friendly_shipping/services/usps/parse_city_state_lookup_response'
 require 'friendly_shipping/services/usps/parse_rate_response'
 
 module FriendlyShipping
@@ -23,7 +27,9 @@ module FriendlyShipping
       LIVE_URL = 'https://secure.shippingapis.com/ShippingAPI.dll'
 
       RESOURCES = {
-        rates: 'RateV4',
+        address_validation: 'Verify',
+        city_state_lookup: 'CityStateLookup',
+        rates: 'RateV4'
       }.freeze
 
       def initialize(login:, test: true, client: Client)
@@ -51,8 +57,8 @@ module FriendlyShipping
       # @return [Result<Array<FriendlyShipping::Rate>>] When successfully parsing, an array of rates in a Success Monad.
       #   When the parsing is not successful or USPS can't give us rates, a Failure monad containing something that
       #   can be serialized into an error message using `to_s`.
-      def rate_estimates(shipment, _carriers, shipping_method: nil)
-        rate_request_xml = SerializeRateRequest.call(shipment: shipment, login: login, shipping_method: shipping_method)
+      def rate_estimates(shipment, options = {})
+        rate_request_xml = SerializeRateRequest.call(shipment: shipment, login: login, shipping_method: options[:shipping_method])
         request = FriendlyShipping::Request.new(url: base_url, body: "API=#{RESOURCES[:rates]}&XML=#{CGI.escape rate_request_xml}")
 
         client.post(request).bind do |response|
@@ -60,6 +66,40 @@ module FriendlyShipping
         end
       end
 
+      # Validate an address.
+      # @param [Physical::Location] location The address we want to verify
+      # @return [Result<ApiResult<Array<Physical::Location>>>] The response data from UPS encoded in a
+      #   `Physical::Location` object. Name and Company name are always nil, the
+      #   address lines will be made conformant to what USPS considers right. The returned location will
+      #   have the address_type set if possible.
+      def address_validation(location)
+        address_validation_request_xml = SerializeAddressValidationRequest.call(location: location, login: login)
+        request = FriendlyShipping::Request.new(
+          url: base_url,
+          body: "API=#{RESOURCES[:address_validation]}&XML=#{CGI.escape address_validation_request_xml}"
+        )
+
+        client.post(request).bind do |response|
+          ParseAddressValidationResponse.call(response: response, request: request)
+        end
+      end
+
+      # Find city and state for a given ZIP code
+      # @param [Physical::Location] location A location object with country and ZIP code set
+      # @return [Result<ApiResult<Array<Physical::Location>>>] The response data from USPS encoded in a
+      #   `Physical::Location` object. Country, City and ZIP code will be set, everything else nil.
+      def city_state_lookup(location)
+        city_state_lookup_request_xml = SerializeCityStateLookupRequest.call(location: location, login: login)
+        request = FriendlyShipping::Request.new(
+          url: base_url,
+          body: "API=#{RESOURCES[:city_state_lookup]}&XML=#{CGI.escape city_state_lookup_request_xml}"
+        )
+
+        client.post(request).bind do |response|
+          ParseCityStateLookupResponse.call(response: response, request: request)
+        end
+      end
+
       private
 
       def base_url

data/lib/friendly_shipping/services/usps/parse_address_validation_response.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class Usps
+      class ParseAddressValidationResponse
+        class << self
+          # Parse a response from USPS' address validation API
+          #
+          # @param [FriendlyShipping::Request] request The request that was used to obtain this Response
+          # @param [FriendlyShipping::Response] response The response that USPS returned
+          # @return [Result<FriendlyShipping::AddressValidationResult>]
+          def call(request:, response:)
+            # Filter out error responses and directly return a failure
+            parsing_result = ParseXMLResponse.call(response.body, 'AddressValidateResponse')
+            parsing_result.fmap do |xml|
+              address = xml.root.at('Address')
+              suggestions = [
+                Physical::Location.new(
+                  address1: address&.at('Address2')&.text, # USPS swaps Address1 and Address2 in the response
+                  address2: address&.at('Address1')&.text,
+                  city: address&.at('City')&.text,
+                  region: address&.at('State')&.text,
+                  zip: address&.at('Zip5')&.text,
+                  country: 'US'
+                )
+              ]
+              FriendlyShipping::ApiResult.new(
+                suggestions,
+                original_request: request,
+                original_response: response
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/usps/parse_city_state_lookup_response.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class Usps
+      class ParseCityStateLookupResponse
+        class << self
+          # Parse a response from USPS' city/state lookup API
+          #
+          # @param [FriendlyShipping::Request] request The request that was used to obtain this Response
+          # @param [FriendlyShipping::Response] response The response that USPS returned
+          # @return [Result<FriendlyShipping::AddressValidationResult>]
+          def call(request:, response:)
+            # Filter out error responses and directly return a failure
+            parsing_result = ParseXMLResponse.call(response.body, 'CityStateLookupResponse')
+            parsing_result.fmap do |xml|
+              address = xml.root.at('ZipCode')
+              suggestions = [
+                Physical::Location.new(
+                  city: address&.at('City')&.text,
+                  region: address&.at('State')&.text,
+                  zip: address&.at('Zip5')&.text,
+                  country: 'US'
+                )
+              ]
+              FriendlyShipping::ApiResult.new(
+                suggestions,
+                original_request: request,
+                original_response: response,
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/usps/parse_rate_response.rb

@@ -16,19 +16,20 @@ module FriendlyShipping
           # @param [FriendlyShipping::Request] request The request that was used to obtain this Response
           # @param [FriendlyShipping::Response] response The response that USPS returned
           # @param [Physical::Shipment] shipment The shipment object we're trying to get results for
-          # @return [Result<Array<FriendlyShipping::Rate>>] When successfully parsing, an array of rates in a Success Monad.
+          # @return [Result<ApiResult<Array<FriendlyShipping::Rate>>>] When successfully parsing, an array of rates in a Success Monad.
           def call(request:, response:, shipment:)
             # Filter out error responses and directly return a failure
             parsing_result = ParseXMLResponse.call(response.body, 'RateV4Response')
+            rates = []
             parsing_result.fmap do |xml|
               # Get all the possible rates for each package
               rates_by_package = rates_from_response_node(xml, shipment)
 
-              SHIPPING_METHODS.map do |shipping_method|
+              rates = SHIPPING_METHODS.map do |shipping_method|
                 # For every package ...
-                matching_rates = rates_by_package.map do |package, rates|
+                matching_rates = rates_by_package.map do |package, package_rates|
                   # ... choose the rate that fits this package best.
-                  ChoosePackageRate.call(shipping_method, package, rates)
+                  ChoosePackageRate.call(shipping_method, package, package_rates)
                 end.compact # Some shipping rates are not available for every shipping method.
 
                 # in this case, go to the next shipping method.
@@ -38,11 +39,15 @@ module FriendlyShipping
                 FriendlyShipping::Rate.new(
                   amounts: matching_rates.map(&:amounts).reduce({}, :merge),
                   shipping_method: shipping_method,
-                  data: matching_rates.first.data,
-                  original_request: request,
-                  original_response: response
+                  data: matching_rates.first.data
                 )
               end.compact
+
+              ApiResult.new(
+                rates,
+                original_request: request,
+                original_response: response
+              )
             end
           end
 

data/lib/friendly_shipping/services/usps/parse_xml_response.rb

@@ -5,13 +5,13 @@ module FriendlyShipping
     class Usps
       class ParseXMLResponse
         extend Dry::Monads::Result::Mixin
-        ERROR_ROOT_TAG = 'Error'
+        ERROR_TAG = 'Error'
 
         class << self
           def call(response_body, expected_root_tag)
             xml = Nokogiri.XML(response_body)
 
-            if xml.root.nil? || ![expected_root_tag, ERROR_ROOT_TAG].include?(xml.root.name)
+            if xml.root.nil? || ![expected_root_tag, 'Error'].include?(xml.root.name)
               Failure('Invalid document')
             elsif request_successful?(xml)
               Success(xml)
@@ -25,13 +25,13 @@ module FriendlyShipping
           private
 
           def request_successful?(xml)
-            xml.xpath('Error/Number')&.text.blank?
+            xml.xpath('//Error/Number')&.text.blank?
           end
 
           def error_message(xml)
-            number = xml.xpath('Error/Number')&.text
-            desc = xml.xpath('Error/Description')&.text
-            [number, desc].select(&:present?).join(': ').presence || 'USPS could not process the request.'
+            number = xml.xpath('//Error/Number')&.text
+            desc = xml.xpath('//Error/Description')&.text
+            [number, desc].select(&:present?).join(': ').presence&.strip || 'USPS could not process the request.'
           end
         end
       end

data/lib/friendly_shipping/services/usps/serialize_address_validation_request.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class Usps
+      class SerializeAddressValidationRequest
+        def self.call(location:, login:)
+          xml_builder = Nokogiri::XML::Builder.new do |xml|
+            xml.AddressValidateRequest USERID: login do
+              xml.Address do
+                xml.Address1 location.address2 # USPS swaps Address1 and Address2 in the request
+                xml.Address2 location.address1
+                xml.City location.city
+                xml.State location.region.code
+                xml.Zip5 location.zip
+                xml.Zip4
+              end
+            end
+          end
+          xml_builder.to_xml
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/usps/serialize_city_state_lookup_request.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class Usps
+      class SerializeCityStateLookupRequest
+        def self.call(location:, login:)
+          xml_builder = Nokogiri::XML::Builder.new do |xml|
+            xml.CityStateLookupRequest(USERID: login) do
+              xml.ZipCode do
+                xml.Zip5 location.zip
+              end
+            end
+          end
+          xml_builder.to_xml
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/usps/serialize_rate_request.rb

@@ -33,10 +33,10 @@ module FriendlyShipping
                     container = CONTAINERS[package.properties[:box_name] || :rectangular]
                     xml.Container(container)
                     xml.Size(size_code)
-                    xml.Width("%0.2f" % package.width.convert_to(:inches).value.to_f)
-                    xml.Length("%0.2f" % package.length.convert_to(:inches).value.to_f)
-                    xml.Height("%0.2f" % package.height.convert_to(:inches).value.to_f)
-                    xml.Girth("%0.2f" % girth(package))
+                    xml.Width("%<width>0.2f" % { width: package.width.convert_to(:inches).value.to_f })
+                    xml.Length("%<length>0.2f" % { length: package.length.convert_to(:inches).value.to_f })
+                    xml.Height("%<height>0.2f" % { height: package.height.convert_to(:inches).value.to_f })
+                    xml.Girth("%<girth>0.2f" % { girth: girth(package) })
                     xml.Machinable(machinable(package))
                   end
                 end

data/lib/friendly_shipping/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
-  VERSION = "0.2.6"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: friendly_shipping
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.3.0
 platform: ruby
 authors:
 - Martin Meyerhoff
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-07-15 00:00:00.000000000 Z
+date: 2019-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: data_uri
@@ -158,6 +158,8 @@ files:
 - bin/setup
 - friendly_shipping.gemspec
 - lib/friendly_shipping.rb
+- lib/friendly_shipping/api_failure.rb
+- lib/friendly_shipping/api_result.rb
 - lib/friendly_shipping/bad_request.rb
 - lib/friendly_shipping/carrier.rb
 - lib/friendly_shipping/label.rb
@@ -174,10 +176,14 @@ files:
 - lib/friendly_shipping/services/ship_engine/serialize_rate_estimate_request.rb
 - lib/friendly_shipping/services/ups.rb
 - lib/friendly_shipping/services/ups/client.rb
+- lib/friendly_shipping/services/ups/parse_address_validation_response.rb
+- lib/friendly_shipping/services/ups/parse_city_state_lookup_response.rb
 - lib/friendly_shipping/services/ups/parse_rate_response.rb
 - lib/friendly_shipping/services/ups/parse_xml_response.rb
 - lib/friendly_shipping/services/ups/serialize_access_request.rb
 - lib/friendly_shipping/services/ups/serialize_address_snippet.rb
+- lib/friendly_shipping/services/ups/serialize_address_validation_request.rb
+- lib/friendly_shipping/services/ups/serialize_city_state_lookup_request.rb
 - lib/friendly_shipping/services/ups/serialize_package_node.rb
 - lib/friendly_shipping/services/ups/serialize_rating_service_selection_request.rb
 - lib/friendly_shipping/services/ups/shipping_methods.rb
@@ -185,9 +191,13 @@ files:
 - lib/friendly_shipping/services/usps/choose_package_rate.rb
 - lib/friendly_shipping/services/usps/client.rb
 - lib/friendly_shipping/services/usps/machinable_package.rb
+- lib/friendly_shipping/services/usps/parse_address_validation_response.rb
+- lib/friendly_shipping/services/usps/parse_city_state_lookup_response.rb
 - lib/friendly_shipping/services/usps/parse_package_rate.rb
 - lib/friendly_shipping/services/usps/parse_rate_response.rb
 - lib/friendly_shipping/services/usps/parse_xml_response.rb
+- lib/friendly_shipping/services/usps/serialize_address_validation_request.rb
+- lib/friendly_shipping/services/usps/serialize_city_state_lookup_request.rb
 - lib/friendly_shipping/services/usps/serialize_rate_request.rb
 - lib/friendly_shipping/services/usps/shipping_methods.rb
 - lib/friendly_shipping/shipping_method.rb