README.md in friendly_shipping-0.2.6 vs README.md in friendly_shipping-0.3.0

@@ -1,11 +1,9 @@
-# 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.
+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.
 
-TODO: Delete this and the text above, and describe your gem
-
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -20,24 +18,91 @@
 
     $ gem install friendly_shipping
 
 ## 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
 
 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/[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
 
 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/[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).