# 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:

```ruby
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](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, 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:

```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
- `#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:

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

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

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](https://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](http://contributor-covenant.org) code of conduct.

## License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

## 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/friendlycart/friendly_shipping/blob/master/CODE_OF_CONDUCT.md).