shippo 1.0.4 → 2.0.0

data/.travis.yml

@@ -0,0 +1,16 @@
+language: ruby
+env:
+  - CODECLIMATE_REPO_TOKEN=ab88ea1c6e1d5356540704cb4dd58eeaf256f4ac7b454852f256091bf205d9e2
+rvm:
+  - 2.2.3
+  - 2.3.0
+script: "gem install bundler --no-ri --no-rdoc; bundle exec rspec"
+notifications:
+  slack:
+    rooms:
+    - shippo:JOD4pUgjGlhSJ1s8mNKUTxKB#devcistatus
+  email:
+    recipients:
+      - kigster@gmail.com
+    on_success: change
+    on_failure: always

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+####  2.0.0-beta  July 7th, 2016
+
+ - Added a concept of List transformer in order to properly coerce
+   received hashes into proper model objects
+ - updated to_s and inspect on models and ApiObject
+ - added a large number of new tests
+
+####  2.0.0-alpha June, 2016
+
+ - Library refactoring and reorganization
+    - Consolidating operations under the Shippo::API::Operations namespace
+    - Instead of doing `include <operation module>` using new `operations :list, :create, ... ` class methods
+    - Instead of setting a global class instance variable `@custom_url`, use new class method `url "/custom/uri"` to set the custom URI component
+    - Added `actievesupport` gem dependency for `#pluralize` and `#constantize` instead of rolling our own
+    - Token should now be set via `Shippo::API.token =`, although `Shippo.api_token = ` is also supported
+    - Renamed `Api` to `API` in line with Ruby conventions
+    - Consolidated `Resource` and `ContainerObject` into one class
+    - Extracted a new class `Shippo::API::Request`
+    - Extracted `#validate` and `#rates` into operations
+    - Created 2nd-level namspaces to separate models from operations from utility classes such as `Request` and `Resource`
+    - Consolidated models under Shippo namespace
+    - Converted existing unit test into an RSpec
+ - Improved overall exception handling
+    - split up and organized Exceptions
+    - mapping TCP-specific errors to `ConnectionError`
+    - mapping JSON parser and server errors
+ - Improved the Example script
+    - Added exception handling clause similar to how the API should be used in real life
+    - Reading API token from the environment
+    - Moved example script into `bin/example`
+ - Miscellaneous:
+    - Reformatting and updated README
+    - Added a rake task for documentation generation `rake shippo:doc`
+    - Added Yardoc parameters and class descriptions to key entities
+    - Updated syntax for Ruby 2+
+    - Renamed the gem from `shippo` to `shippo-api`.
+
+####  1.0.4 June 19th, 2015
+
+- added support for Carrier Accounts
+
+#### 1.0.3 June 18th, 2015
+
+- changed auth to use ShippoToken (vs username and password)
+
+####  1.0.2 Aug 25th, 2014
+
+- added optional parameter <currency> for shipment.rates()
+- added validate method to address
+- added manifest, customs_item, customs_declaration, and refund classes

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+gem "codeclimate-test-reporter", group: :test, require: nil
+
+# Specify your gem's dependencies in counter-cache.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,39 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+directories %w(lib spec)
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/README.md

@@ -0,0 +1,288 @@
+
+# Shippo API – Ruby Wrapper for Shippo API
+
+[![Build Status](https://travis-ci.org/kigster/shippo-ruby-client.svg?branch=master)](https://travis-ci.org/kigster/shippo-ruby-client) 
+[![Code Climate](https://codeclimate.com/github/kigster/shippo-ruby-client/badges/gpa.svg)](https://codeclimate.com/github/kigster/shippo-ruby-client) 
+[![Test Coverage](https://codeclimate.com/github/kigster/shippo-ruby-client/badges/coverage.svg?refresh=1)](https://codeclimate.com/github/kigster/shippo-ruby-client/coverage)
+[![Issue Count](https://codeclimate.com/github/kigster/shippo-ruby-client/badges/issue_count.svg?refresh=1)](https://codeclimate.com/github/kigster/shippo-ruby-client)
+
+Shippo is a shipping API that connects you with multiple shipping carriers (such as USPS, UPS, DHL, Canada Post, Australia Post, UberRUSH and many [others](https://goshippo.com/shipping-carriers/)) through one interface.
+
+Our API provides in depth support of cross-carrier functionality. Here are just some of the features we support for USPS, FedEx, UPS and many others via the API.
+
+## Core Functionality
+
+For most major carriers (USPS, UPS, FedEx and most others) our API supports:
+
+* Querying for shipping rates
+* Creating and printing labels
+* Tracking shipments
+
+#### Additional Features for USPS
+
+
+For USPS, the API additionally supports:
+
+  * US Address validation
+  * Scan forms
+  * Signature
+  * Certified mail
+  * Delivery confirmation
+  * etc.
+
+#### FedEx
+
+For FedEx, the API additionally supports:
+
+  * Signature and adult signature confirmation
+  * FedEx Smartpost
+
+### UPS
+
+For UPS, the API additionally supports:
+
+  * Signature and adult signature confirmation
+  * UPS Mail Innovations
+  * UPS SurePost
+
+The complete list of carrier supported features is [here](https://goshippo.com/shipping-api/carriers).
+
+### About Shippo
+
+Connect with multiple different carriers, get discounted shipping labels, track parcels, and much more with just one integration. You can use your own carrier accounts or take advantage of our deeply discounted rates. Using Shippo makes it easy to deal with multiple carrier integrations,  rate shopping, tracking and other parts of the shipping workflow. We provide the API and dashboard for all your shipping needs.
+
+The API is free to use. You only pay when you print a live label from a carrier.  Use test labels during development to avoid all fees.
+
+You do need a Shippo account to use our API. Don't have an account? Sign up at [https://goshippo.com/](https://goshippo.com/).
+
+## Installation
+
+This library is distributed as a ruby gem, therefore youcan install it via adding the following line to your `Gemfile`:
+
+```
+gem 'shippo'
+```
+
+If you prefer to use the latest version of the library, just point your Gemfile to our github repo:
+
+```
+gem 'shippo', git: 'https://github.com/goshippo/shippo-ruby-client'
+```
+
+Or you can install the gem using the `gem` command:
+
+```bash
+gem install shippo
+```
+
+## Usage 
+
+
+```ruby
+require 'shippo/api'
+
+# Setup your API token
+Shippo.api_key = 'aff988f77afa0fdfdfadf'  # not an actual valid token
+
+# Setup query parameter hash
+params   = { object_purpose: 'PURCHASE',
+              async:          false,
+              address_from:   {
+                object_purpose: 'PURCHASE',
+                name:           'Mr Hippo',
+                company:        'Shippo',
+                street1:        '215 Clayton St.',
+                street2:        '',
+                city:           'San Francisco',
+                state:          'CA',
+                zip:            '94117',
+                country:        'US',
+                phone:          '+1 555 341 9393',
+                email:          'support@goshippo.com' },
+              address_to:     {
+                object_purpose: 'PURCHASE',
+                name:           'Mrs Hippo"',
+                company:        'San Diego Zoo',
+                street1:        '2920 Zoo Drive',
+                city:           'San Diego',
+                state:          'CA',
+                zip:            '92101',
+                country:        'US',
+                phone:          '+1 555 341 9393',
+                email:          'hippo@goshippo.com' },
+              parcel:         {
+                length:        5,
+                width:         2,
+                height:        5,
+                distance_unit: :in,
+                weight:        2,
+                mass_unit:     :lb }
+} 
+
+# Make our API call 
+@shipment = Shippo::Shipment.create(params)
+@shipment.success?
+# => true
+@shipment.object.status
+# => 'SUCCESS'
+@shipment.status # forwarded to #object
+# => 'SUCCESS'
+@shipment.state
+# => 'VALID'
+```
+
+Let's take a quick look at what the `Address` object looks like:
+
+```ruby
+require 'awesome_print'
+ap @shipment
+# {
+#        "carrier_accounts" => [],
+#            "address_from" => "a704eada7494bb1be6184ef64b1646db",
+#              "address_to" => "92b43fbfa3641644beb32996042eb57a",
+#                  "parcel" => "92df4baac73ea6131940c0d315d70a7d",
+#         "submission_type" => "DROPOFF",
+#         "submission_date" => "2016-07-06T20:33:02.211Z",
+#          "address_return" => "a1f64ba14b7e41b86a0446de4ebbd769",
+#               "return_of" => nil,
+#     "customs_declaration" => nil,
+#        "insurance_amount" => "0",
+#      "insurance_currency" => nil,
+#                   "extra" => {},
+#             "reference_1" => "",
+#             "reference_2" => "",
+#               "rates_url" => "https://api.goshippo.com/v1/shipments/a336daf87a8e442992a68daa6622758f/rates/",
+#                "messages" => [ ] # ommitted for brevity,
+#              "rates_list" => [ ] # ommitted for brevity.
+# }
+```
+
+#### List Handling
+
+In the case when the API returns a hash with one of the hash values being an array of entities, and if the corresponding key can be mapped into one of the existing API models, then each of the members of the array is coerced from a hash into an object of the model's type.
+
+In the example below we are showing the result of such transformation where the `rates_list` contains a list of fully constructed objects of type `Shippo::Rate` after being coerced from a hash.
+  
+```ruby
+ap @shipment.rates_list.first
+# => 
+# {
+#                     "shipment" => "20f25e44b16b4051b6dd910cb66fd27b",
+#             "available_shippo" => true,
+#                   "attributes" => [],
+#                       "amount" => "8.51",
+#                     "currency" => "USD",
+#                 "amount_local" => "8.51",
+#               "currency_local" => "USD",
+#                     "provider" => "FedEx",
+#            "provider_image_75" => "https://shippo-static.s3.amazonaws.com/providers/75/FedEx.png",
+#           "provider_image_200" => "https://shippo-static.s3.amazonaws.com/providers/200/FedEx.png",
+#            "servicelevel_name" => "Ground",
+#           "servicelevel_token" => "fedex_ground",
+#           "servicelevel_terms" => "",
+#                         "days" => 2,
+#                   "arrives_by" => nil,
+#               "duration_terms" => "",
+#                    "trackable" => true,
+#                    "insurance" => false,
+#       "insurance_amount_local" => "0.00",
+#     "insurance_currency_local" => nil,
+#             "insurance_amount" => "0.00",
+#           "insurance_currency" => nil,
+#            "delivery_attempts" => nil,
+#            "outbound_endpoint" => "door",
+#             "inbound_endpoint" => "door",
+#                     "messages" => [],
+#              "carrier_account" => "4b1940bc69524163b669asd361842db",
+#                         "test" => true
+# }
+@shipment.rates.first.owner
+# ⤷ unittest@gmail.com
+@shipment.rates.first.class
+# ⤷ Shippo::Rate
+```
+
+#### Resource ID and Other Object Fields
+
+Shippo API returns several generalized fields for each valid resource, that being with 'object_' – for example, `object_id`, `object_owner`, etc.  In this library we move these fields out of the main model, and into an instance of `Shippo::API::ApiObject`. However the fields can still be accessed on the main model via generated accessors.
+ 
+Unfortunately Shippo API also returns `object_id`, which in Ruby has a special meaning: it's the pointer address of any object. Overwriting this field causes all sorts of issues.
+
+For this reason we are mapping `object_id` to `resource_id`, as soon as the hash is passed in to initialize `ApiObject`.
+
+The following console output demonstrates many ways of accessing `object_` fields:
+
+```ruby
+@shipment.object_id    # this is the Ruby object pointer
+# ⤷ 70206221831520  
+@shipment.resource_id  # this is the API id (note: deprecated accessor)
+# ⤷ 20f25e44b16b4051b6dd910cb66fd27b
+@shipment.object.id    # which is actually just this
+# ⤷ 20f25e44b16b4051b6dd910cb66fd27b
+@shipment.id           # but it can also be accessed this way too
+# ⤷ 20f25e44b16b4051b6dd910cb66fd27b
+```
+
+And with the rest of the `object_` fields:
+
+``` ruby
+@shipment.object.owner    # this is whether 'object_owner' is stored
+# ⤷ valued_customer@gmail.com
+@shipment.object_owner    # deprecated accessor method
+# ⤷ valued_customer@gmail.com
+@shipment.owner           # forwarded alias to #object.owner
+# ⤷ valued_customer@gmail.com
+```
+
+Here is the fully construted `ApiObject` instance, attached to our `@shipment`:
+
+```ruby
+ap @shipment.object
+# {
+#     :created => 2016-07-06 20:44:47 UTC,
+#     :updated => 2016-07-06 20:44:47 UTC,
+#       :owner => "valued_customer@gmail.com",
+#       :state => #<Shippo::API::Category::State:0x007fd88be8aa38 @name=:state, @value=:valid>,
+#      :status => #<Shippo::API::Category::Status:0x007fd88be82e28 @name=:status, @value=:success>,
+#     :purpose => #<Shippo::API::Category::Purpose:0x007fd88be985e8 @name=:purpose, @value=:purchase>,
+#          :id => "20f25e44b16b4051b6dd910cb66fd27b"
+# }
+```
+
+#### Validation 
+
+In general this gem does not currently perform validation, *except* in the cases when enumerations are used. The gem automatically converts a response containing keys matching one of the known categories (such as `Shippo::API::Category::Status` and it's value into one of the constants, such as `SUCCESS`. 
+
+### Using Provided Example File
+
+Look at `bin/example` for more code sample.
+
+You can actually run this file, but first you should set your API token in the environment:
+
+```bash
+export SHIPPO_TOKEN="<your token here>"
+bin/example
+```
+
+## Gem Versioning Notes
+
+Version 2 and up of this library works with Ruby 2.2 and later, and is not backwards compatible. __Version 1.0.4__ of this library is the last version of the gem `shippo`, and the last version supporting ruby 1.8 and 1.9.
+
+The intent, however, is to completely deprecate `shippo` gem in the near future.
+
+### If you are still using Ruby 1.8 or 1.9
+
+If you are still using an older version of Ruby, please make sure to use the last 1.X version of this library, which is currently the [tag v1.0.4](https://github.com/goshippo/shippo-ruby-client/tree/v1.0.4).
+
+## Documentation
+
+Please see [https://goshippo.com/shipping-api/](https://goshippo.com/shipping-api/) for up-to-date documentation.
+
+For Ruby class documentation, please run the following rake task:
+
+```bash
+bundle install
+bundle exec rake doc:read # preview documentation in the browser
+```
+
+This task will generate documentation using [Yard](https://yardoc.org) and then open the browser with the generated index.html.

data/Rakefile

@@ -0,0 +1,24 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rake/clean'
+require_relative 'lib/shippo/tasks/shippo'
+
+CLEAN.include %w(pkg coverage *.gem)
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
+  STDERR.puts %Q(Unable to find rspec library.\nPlease run "bundle install" and then "bundle exec rake <task>")
+  exit 1
+end
+
+begin
+  require 'bundler'
+  require 'bundler/gem_tasks'
+rescue LoadError
+  STDERR.puts %Q(Unable to find Bundler.\nPlease run "gem install bundler" first.)
+  exit 2
+end
+
+task :default => [:spec]

data/bin/example

@@ -0,0 +1,114 @@
+#!/usr/bin/env ruby
+#
+# © 2016 Shippo, Inc.
+#
+# License: MIT
+#
+lib = File.expand_path('../../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'bundler/setup'
+require 'shippo/api'
+require 'shippo/api/category'
+require 'shippo/exceptions/api_error'
+require 'colored2'
+require 'awesome_print'
+require 'json'
+
+# This example demonstrates how to purchase a label for a domestic US shipment.
+# Please set SHIPPO_TOKEN in the environment
+Shippo::API.token = ENV['SHIPPO_TOKEN']
+Shippo::API.debug = false # set to true for debugging output
+
+# Create address_from object
+address_from      = {
+  :object_purpose => 'PURCHASE',
+  :name           => 'Mr Hippo',
+  :company        => 'Shippo',
+  :street1        => '215 Clayton St.',
+  :street2        => '',
+  :city           => 'San Francisco',
+  :state          => 'CA',
+  :zip            => '94117',
+  :country        => 'US',
+  :phone          => '+1 555 341 9393',
+  :email          => 'support@goshippo.com' }
+
+# Create address_to object
+address_to        = {
+  :object_purpose => 'PURCHASE',
+  :name           => 'Mrs Hippo"',
+  :company        => 'San Diego Zoo',
+  :street1        => '2920 Zoo Drive',
+  :city           => 'San Diego',
+  :state          => 'CA',
+  :zip            => '92101',
+  :country        => 'US',
+  :phone          => '+1 555 341 9393',
+  :email          => 'hippo@goshippo.com' }
+
+# Create parcel object
+parcel            = {
+  :length        => 5,
+  :width         => 2,
+  :height        => 5,
+  :distance_unit => :in,
+  :weight        => 2,
+  :mass_unit     => :lb }
+
+hash = { :object_purpose => 'PURCHASE',
+         :address_from   => address_from,
+         :address_to     => address_to,
+         :parcel         => parcel,
+         :async          => false }
+puts 'Making first API call for shipment rates...'.blue.bold
+
+begin
+  shipment = Shippo::Shipment.create(hash)
+  raise Shippo::Exceptions::UnsuccessfulResponseError.new(shipment.object.inspect) unless shipment.success?
+  File.open('example-shipment.json', 'w') do |file|
+    file.puts JSON.dump(shipment.to_hash)
+  end
+rescue Shippo::Exceptions::APIServerError => e
+  puts "Server returned an error:\n#{e.inspect}".bold.red
+  exit 3
+rescue Shippo::Exceptions::ConnectionError
+  puts 'Error connecting to remote host. Is your Internet working?'.bold.red
+  exit 2
+rescue Shippo::Exceptions::AuthenticationError
+  if Shippo::API.token
+    puts "Token '#{Shippo::API.token}' does not appear to be valid.".bold.red
+    puts 'Access denied.'
+  else
+    puts 'Please set authentication token in the environment:'.bold.red
+    puts 'export SHIPPO_TOKEN="<your token here>"'
+    puts 'and re-run the example.'
+  end
+  exit 1
+end
+
+# Get the desired rate according to your business logic
+# We select the first rate in this example
+rate = shipment.rates_list.first
+puts 'RATES:'.bold.green.underlined
+ap(rate)
+
+puts "Purchasing a #{rate} label!"
+
+# Purchase the desired rate (create a Transaction object)
+transaction = Shippo::Transaction.create(rate: rate.id, async: false)
+
+if transaction.success?
+  # noinspection RubyResolve
+  puts 'Transaction OK'.bold.green.underlined + "\n"
+
+  puts "Label URL      : #{
+  # noinspection RubyResolve
+  transaction.label_url.bold.yellow }"
+  puts "Tracking NO    : #{
+  # noinspection RubyResolve
+  transaction.tracking_number.to_s.bold.yellow}"
+else
+  puts 'Transaction ERROR'.bold.red
+  puts transaction.messages.bold.red
+end