/friendly_shipping

A friendly shipping provider API wrapper

Primary LanguageRubyMIT LicenseMIT

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.

Installation

Add this line to your application's Gemfile:

gem 'friendly_shipping'

And then execute:

$ bundle

Or install it yourself as:

$ gem install friendly_shipping

Usage

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

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:

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

UPS (United Parcel Service)

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.

USPS (United States Postal Service)

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.

UPS Freight

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

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.

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.

Contributing

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.

License

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

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.