friendly_shipping 0.3.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9fae2b417bddc3fd2cc6cb4a6c07212e8efb3c65
-  data.tar.gz: 674d279b79b45e5f72d116a64b83c1215192f805
+  metadata.gz: 14d1848557e65a7773aaa0683b4af131c2784181
+  data.tar.gz: 1d63935b99e3e09cfec828663ab53956224a67e2
 SHA512:
-  metadata.gz: bdf22d97688944e2cd7d0c68ee896e3c41ab15abe27129398cd257dbd89b8dfa601e11f7fb44e5de330d57660580fec577f7ac74acb8f35984c9ce399e4d4fa7
-  data.tar.gz: 52ce6aedde1900838fda5e9d16feffd5a4c911de78fbed324485f20f2d9c906ecda6f1c6a03037292e1a0a625307fab8b5750fe2b9dea3273a82591f5da6a225
+  metadata.gz: 7d894f9c105b238dcbfed6d94246e5206274e29d5fbbec6a82d1cc783a01538c8a0465e321a720ccaeeb9662d2e36d2d6d84b7087b714d44b5249a2f555bfa6e
+  data.tar.gz: 9d8b29758884d37bb4fb8eca4aee2f7c58c797115972807fce68d9c9b7cb43608f3cdf4e07ec504ed8f04b8cec377686169c79b611e38bfb99d28964bd096a55

data/.env.template

@@ -3,6 +3,7 @@
 # Only pass along how those passwords/info are reference via ENV VARS
 
 SHIPENGINE_API_KEY=Ship Engine API key
+SHIPENGINE_CARRIER_ID=Carrier ID from your ShipEngine account to run test labels with
 
 UPS_KEY=UPS API access key
 UPS_LOGIN=UPS login name

data/.gitignore

@@ -17,3 +17,4 @@
 # Gemfile.lock
 Gemfile.lock
 .env
+coverage

data/CHANGELOG.md

@@ -4,22 +4,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.3.4] - 2017-10-28
+## [0.4.0] - 2019-11-11
+
+### Added
+- UPS Freight Service (rates estimation only for now)
+- UPS: Label generation
+
+### Changed
+
+- All API methods now take a shipment, sometimes a typed Options object, and a `debug` flag.
+- There are option classes for shipments, packages, and items. See the spec for UPS Freight about how they work.
 
 ### Changed
 - Add ConsigneeName to Address validation/classification request
 
-## [0.3.3] - 2017-10-25
+## [0.3.3] - 2019-10-25
 
 ### Changed
 - Fix: ShipEngine#labels test mode works again.
 
-## [0.3.2] - 2017-10-25
+## [0.3.2] - 2019-10-25
 
 ### Changed
 - Fix: ShipEngine#labels now works as expected.
 
-## [0.3.1] - 2017-06-20
+## [0.3.1] - 2019-06-20
 ### Added
 - Endpoint for UPS address classification
 

data/Gemfile

@@ -12,5 +12,6 @@ gem 'factory_bot'
 gem 'pry'
 gem 'rspec_junit_formatter'
 gem 'rubocop'
+gem 'simplecov', require: false
 gem 'vcr'
 gem 'webmock'

data/README.md

@@ -25,6 +25,7 @@ The entry point for using FriendlyShipping are the `service` objects that each r
 1. `FriendlyShipping::Services::Ups`
 2. `FriendlyShipping::Services::Usps`
 3. `FriendlyShipping::Services::ShipEngine`
+4. `FriendlyShipping::Services::UpsFreight`
 
 The services are instantiated with the credentials they need as well as a `test` flag to indicate whether to use their respective `sandbox` environments.
 
@@ -47,8 +48,8 @@ service = FriendlyShipping::Services::ShipEngine.new(token: ENV['SHIPENGINE_TOKE
 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, shipping_method:)` - Get labels for a shipments. Currently only supports USPS labels, other services are untested.
+- `#rate_estimates(physical_shipment, options: options)` - Get rate estimates for a shipment
+- `#labels(physical_shipment, options: options)` - Get labels for a shipments. Currently only supports USPS labels, other services are untested.
 - `#void(physical_label)` - Void a label and get the cost refunded
 
 #### UPS (United Parcel Service)
@@ -68,6 +69,7 @@ The following methods are supported:
 
 - `#carriers` - List all configured carriers (always returns UPS)
 - `#rate_estimates(physical_shipment)` - Get rate estimates for a shipment
+- `#labels(physical_shipment, options: options)` - Get labels for a shipment
 - `#address_classification(physical_location)` - Determine whether an address is commercial or residential.
 - `#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.
@@ -90,6 +92,23 @@ The following methods are supported:
 - `#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.
 
+#### UPS Freight
+
+The service class for UPS is `FriendlyShipping::Services::UpsFreight`. It functions quite differently from normal, package-level shipping. Initialize like so:
+
+```rb
+service = FriendlyShipping::Services::UpsFreight.new(
+  key: ENV['UPS_API_KEY'],
+  login: ENV['UPS_API_LOGIN'],
+  password: ENV['UPS_API_PASSWORD'],
+  test: true
+)
+```
+
+The following methods are supported:
+
+- `#rate_estimates(physical_shipment, options: options)` - Get rate estimates for a shipment
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/friendly_shipping.gemspec

@@ -26,7 +26,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "dry-monads", "~> 1.0"
   spec.add_runtime_dependency "money", ">= 6.0.0"
   spec.add_runtime_dependency "nokogiri", ">= 1.6"
-  spec.add_runtime_dependency "physical", "~> 0.4"
+  spec.add_runtime_dependency "physical", ">= 0.4.4"
   spec.add_runtime_dependency "rest-client", "~> 2.0"
   spec.required_ruby_version = '>= 2.4'
 

data/lib/friendly_shipping/api_failure.rb

@@ -4,6 +4,9 @@ module FriendlyShipping
   class ApiFailure
     attr_reader :failure, :original_request, :original_response
 
+    # @param [Object] failure The API failure
+    # @param [FriendlyShipping::Request] original_request The HTTP request (when debugging is enabled)
+    # @param [FriendlyShipping::Response] original_response The HTTP response (when debugging is enabled)
     def initialize(failure, original_request:, original_response:)
       @failure = failure
 

data/lib/friendly_shipping/api_result.rb

@@ -4,6 +4,9 @@ module FriendlyShipping
   class ApiResult
     attr_reader :data, :original_request, :original_response
 
+    # @param [Object] data The API result
+    # @param [FriendlyShipping::Request] original_request The HTTP request (when debugging is enabled)
+    # @param [FriendlyShipping::Response] original_response The HTTP response (when debugging is enabled)
     def initialize(data, original_request: nil, original_response: nil)
       @data = data
 

data/lib/friendly_shipping/carrier.rb

@@ -4,6 +4,12 @@ module FriendlyShipping
   class Carrier
     attr_reader :id, :name, :code, :shipping_methods, :balance, :data
 
+    # @param [Integer] id The carrier's ID
+    # @param [String] name The carrier's name
+    # @param [String] code The carrier's unique code
+    # @param [Array] shipping_methods The shipping methods available on this carrier
+    # @param [Float] balance The remaining balance for this carrier
+    # @param [Hash] data Additional data related to this carrier
     def initialize(id: nil, name: nil, code: nil, shipping_methods: [], balance: nil, data: {})
       @id = id
       @name = name

data/lib/friendly_shipping/http_client.rb

@@ -9,6 +9,7 @@ module FriendlyShipping
 
     attr_reader :error_handler
 
+    # @param [Proc] error_handler Called to handle an error if one occurs
     def initialize(error_handler: method(:wrap_in_failure))
       @error_handler = error_handler
     end

data/lib/friendly_shipping/item_options.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  class ItemOptions
+    attr_reader :item_id
+
+    def initialize(item_id:)
+      @item_id = item_id
+    end
+  end
+end

data/lib/friendly_shipping/label.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'friendly_shipping/types'
+
 module FriendlyShipping
   class Label
     attr_reader :id,
@@ -9,11 +11,19 @@ module FriendlyShipping
                 :label_href,
                 :data,
                 :label_format,
+                :cost,
                 :shipment_cost,
-                :label_data,
-                :original_request,
-                :original_response
+                :label_data
 
+    # @param [Integer] id The label's ID
+    # @param [Integer] shipment_id The label's shipment ID
+    # @param [String] tracking_number The label's tracking number
+    # @param [String] service_code The label's service code
+    # @param [String] label_href The URL for the label
+    # @param [String] label_format The label's format
+    # @param [String] label_data The raw label data
+    # @param [Float] shipment_cost The cost of the shipment
+    # @param [Hash] data Additional data related to the label
     def initialize(
       id: nil,
       shipment_id: nil,
@@ -22,10 +32,9 @@ module FriendlyShipping
       label_href: nil,
       label_format: nil,
       label_data: nil,
+      cost: nil,
       shipment_cost: nil,
-      data: {},
-      original_request: nil,
-      original_response: nil
+      data: {}
     )
       @id = id
       @shipment_id = shipment_id
@@ -33,11 +42,10 @@ module FriendlyShipping
       @service_code = service_code
       @label_href = label_href
       @label_format = label_format
-      @shipment_cost = shipment_cost
+      @cost = FriendlyShipping::Types::Money.optional[cost]
+      @shipment_cost = FriendlyShipping::Types::Money.optional[shipment_cost]
       @label_data = label_data
       @data = data
-      @original_request = original_request
-      @original_response = original_response
     end
   end
 end

data/lib/friendly_shipping/package_options.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  class PackageOptions
+    attr_reader :package_id
+
+    def initialize(
+      package_id:,
+      item_options: Set.new,
+      item_options_class: ItemOptions
+    )
+      @package_id = package_id
+      @item_options = item_options
+      @item_options_class = item_options_class
+    end
+
+    def options_for_item(item)
+      item_options.detect do |item_option|
+        item_option.item_id == item.id
+      end || item_options_class.new(item_id: nil)
+    end
+
+    private
+
+    attr_reader :item_options,
+                :item_options_class
+  end
+end

data/lib/friendly_shipping/rate.rb

@@ -9,10 +9,15 @@ module FriendlyShipping
                 :delivery_date,
                 :warnings,
                 :errors,
-                :data,
-                :original_request,
-                :original_response
+                :data
 
+    # @param [FriendlyShipping::ShippingMethod] shipping_method The rate's shipping method
+    # @param [Hash] amounts The amounts (as Money objects) that make up the rate
+    # @param [Integer] remote_service_id The remote service ID for the rate
+    # @param [Time] delivery_date The delivery date for the rate
+    # @param [Array] warnings Any warnings that were generated
+    # @param [Array] errors Any errors that were generated
+    # @param [Hash] data Additional data related to the rate
     def initialize(
       shipping_method:,
       amounts:,
@@ -20,9 +25,7 @@ module FriendlyShipping
       delivery_date: nil,
       warnings: [],
       errors: [],
-      data: {},
-      original_request: nil,
-      original_response: nil
+      data: {}
     )
       @remote_service_id = remote_service_id
       @shipping_method = shipping_method
@@ -31,8 +34,6 @@ module FriendlyShipping
       @warnings = warnings
       @errors = errors
       @data = data
-      @original_request = original_request
-      @original_response = original_response
     end
 
     def total_amount

data/lib/friendly_shipping/request.rb

@@ -4,6 +4,10 @@ module FriendlyShipping
   class Request
     attr_reader :url, :body, :headers, :debug
 
+    # @param [String] url The HTTP request URL
+    # @param [String] body The HTTP request body
+    # @param [Hash] headers The HTTP request headers
+    # @param [Boolean] debug Whether to debug the request
     def initialize(url:, body: nil, headers: {}, debug: false)
       @url = url
       @body = body

data/lib/friendly_shipping/response.rb

@@ -4,6 +4,9 @@ module FriendlyShipping
   class Response
     attr_reader :status, :body, :headers
 
+    # @param [Integer] status The HTTP response status code
+    # @param [String] body The HTTP response body
+    # @param [Hash] headers The HTTP response headers
     def initialize(status:, body:, headers:)
       @status = status
       @body = body

data/lib/friendly_shipping/services/ship_engine.rb

@@ -9,6 +9,9 @@ require 'friendly_shipping/services/ship_engine/serialize_rate_estimate_request'
 require 'friendly_shipping/services/ship_engine/parse_label_response'
 require 'friendly_shipping/services/ship_engine/parse_void_response'
 require 'friendly_shipping/services/ship_engine/parse_rate_estimate_response'
+require 'friendly_shipping/services/ship_engine/rate_estimates_options'
+require 'friendly_shipping/services/ship_engine/label_options'
+require 'friendly_shipping/services/ship_engine/label_package_options'
 
 module FriendlyShipping
   module Services
@@ -43,22 +46,20 @@ module FriendlyShipping
       #
       # @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.
+      # @options [FriendlyShipping::Services::ShipEngine::RateEstimatesOptions] The options relevant to estimating rates. See object description.
       #
       # @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, selected_carriers: nil, debug: false)
-        selected_carriers ||= carriers.value!.data
+      def rate_estimates(shipment, options: FriendlyShipping::Services::ShipEngine::RateEstimatesOptions.new, debug: false)
         request = FriendlyShipping::Request.new(
           url: API_BASE + 'rates/estimate',
-          body: SerializeRateEstimateRequest.call(shipment: shipment, carriers: selected_carriers).to_json,
+          body: SerializeRateEstimateRequest.call(shipment: shipment, options: options).to_json,
           headers: request_headers,
           debug: debug
         )
         client.post(request).bind do |response|
-          ParseRateEstimateResponse.call(response: response, request: request, carriers: selected_carriers)
+          ParseRateEstimateResponse.call(response: response, request: request, options: options)
         end
       end
 
@@ -67,16 +68,14 @@ module FriendlyShipping
       # @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.
-      # @param [FriendlyShipping::ShippingMethod] shipping_method The shipping method we want to use.
-      #   Specifically, the "#service_code" will be serialized. If a carrier is set, it's `#id` will
-      #   also be sent to ShipEngine.
+      # @param [FriendlyShipping::Services::ShipEngine::LabelOptions] The options relevant to estimating rates. See object description.
       #
       # @return [Result<ApiResult<Array<FriendlyShipping::Label>>>] The label returned.
       #
-      def labels(shipment, shipping_method:)
+      def labels(shipment, options:)
         request = FriendlyShipping::Request.new(
           url: API_BASE + API_PATHS[:labels],
-          body: SerializeLabelShipment.call(shipment: shipment, shipping_method: shipping_method, test: test).to_json,
+          body: SerializeLabelShipment.call(shipment: shipment, options: options, test: test).to_json,
           headers: request_headers
         )
         client.post(request).fmap do |response|

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/shipment_options'
+
+module FriendlyShipping
+  module Services
+    class ShipEngine
+      # Options for generating ShipEngine labels
+      #
+      # @attribute label_format [Symbol] The format for the label. Possible Values: :png, :zpl and :pdf. Default :pdf
+      # @attribute label_download_type [Symbol] Whether to download directly (`:inline`) or
+      #   obtain a URL to the label (`:url`). Default :url
+      # @attribute package_options [Enumberable<LabelPackageOptions>] Package options for the packages in the shipment
+      #
+      class LabelOptions < FriendlyShipping::ShipmentOptions
+        attr_reader :shipping_method,
+                    :label_format,
+                    :label_download_type
+
+        def initialize(
+          shipping_method:,
+          label_format: :pdf,
+          label_download_type: :url,
+          **kwargs
+        )
+          @shipping_method = shipping_method
+          @label_format = label_format
+          @label_download_type = label_download_type
+          super kwargs.merge(package_options_class: LabelPackageOptions)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/package_options'
+
+module FriendlyShipping
+  module Services
+    class ShipEngine
+      # Options relating to packages in the ShipEngine labels call
+      #
+      # @attribute :package_code [Symbol] The type of package. Possible types can be gotten
+      #    via the ShipEngine API: https://www.shipengine.com/docs/reference/list-carrier-packages/
+      #    If a package type is given, no dimensions will be added to the call (as we can assume the
+      #    carrier knows the dimensions of their packaging types).
+      # @attribute messages [Array<String>] A list of messages to add to the label. No carrier accepts
+      #    more than three messages, and some have restrictions on how many characters are possible.
+      #    We're not validating here though.
+      class LabelPackageOptions < FriendlyShipping::PackageOptions
+        attr_reader :package_code, :messages
+
+        def initialize(package_code: nil, messages: [], **kwargs)
+          @package_code = package_code
+          @messages = messages
+          super kwargs
+        end
+      end
+    end
+  end
+end