FriendlyShipping - the friendly shipping provider API wrapper

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 ShipEngine API.

Add this line to your application's Gemfile:

gem 'friendly_shipping'

And then execute:

$ bundle

Or install it yourself as:

$ gem install friendly_shipping

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
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.

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 to represent the physical world (shipments, packages, addresses, and items).

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.

The service class for ShipEngine is FriendlyShipping::Services::ShipEngine. Initialize like so:

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, 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

The service class for UPS is FriendlyShipping::Services::Ups. Initialize like so:

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
• #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.

The service class for USPS is FriendlyShipping::Services::Usps. Initialize like so:

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.

The service class for UPS is FriendlyShipping::Services::UpsFreight. It functions quite differently from normal, package-level shipping. Initialize like so:

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

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.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

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 code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the FriendlyShipping project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.