shippo 2.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c81860a08b63f74f4ea83ae475411634a7042edf
-  data.tar.gz: 5e7be48cbbc63689dfb61dbd0d3fba5d393d273b
+  metadata.gz: 8d3b05de67775ac91487c358fc1b4e2fb18f99b3
+  data.tar.gz: 6723db701c6494c37d204995db345d12eb2a5a0b
 SHA512:
-  metadata.gz: 7eb36d1cfd0101c246d611e25e414ccb7a75c8eb317bd62bb2b8796bb3861184b22d2616514b372ee377ea7f68e695eba8e9eae31cb61f3f3399e23d025ed2cd
-  data.tar.gz: a9528603a1e4830e243b79b216f441c21c9fbbd63311cbfcf462aacb8dc4bc198f3b534032ed7d0ea64e3ee3653cc5a1cc442db65eeec25c17caa8bd72311c38
+  metadata.gz: 04b98b96d950bc69632b0440c7470cbd520badf6c999334dcdd8eb573bf1cbef64fb9b38b6a52f8a6762ddc8eb7dca759fc473a796b9e0c70ae878291f64028e
+  data.tar.gz: bea1fdeaf8273e28d418735e5573177135df28a3d6d1f00ac9704d090447de18685e08843108823cb2b0c04520d300e44727375e13382be1fe48b582315d9c30

data/.travis.yml

@@ -1,9 +1,9 @@
 language: ruby
 env:
-  - CODECLIMATE_REPO_TOKEN=ab88ea1c6e1d5356540704cb4dd58eeaf256f4ac7b454852f256091bf205d9e2
+  - CODECLIMATE_REPO_TOKEN=d00cb259c01f8d6719834225b572d22ba6ea87feec82f1e48bd10ba250e2c4b5
 rvm:
-  - 2.2.3
-  - 2.3.0
+  - 2.2.5
+  - 2.3.1
 script: "gem install bundler --no-ri --no-rdoc; bundle exec rspec"
 notifications:
   slack:

data/README.md

@@ -1,63 +1,20 @@
 
 # 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)
+[![Build Status](https://travis-ci.org/goshippo/shippo-ruby-client.svg?branch=master)](https://travis-ci.org/goshippo/shippo-ruby-client)
+[![Code Climate](https://codeclimate.com/github/goshippo/shippo-ruby-client/badges/gpa.svg)](https://codeclimate.com/github/goshippo/shippo-ruby-client)
+[![Test Coverage](https://codeclimate.com/github/goshippo/shippo-ruby-client/badges/coverage.svg?refresh=1)](https://codeclimate.com/github/goshippo/shippo-ruby-client/coverage)
+[![Issue Count](https://codeclimate.com/github/goshippo/shippo-ruby-client/badges/issue_count.svg?refresh=1)](https://codeclimate.com/github/goshippo/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.
+Shippo is a shipping API that connects you with [multiple shipping carriers](https://goshippo.com/carriers/) (such as USPS, UPS, DHL, Canada Post, Australia Post, UberRUSH and many others) 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.
+Print a shipping label in 10 mins using our default USPS and DHL Express accounts. No need to register for a carrier account to get started.
 
-## 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/).
+You will need to [register for a Shippo account](https://goshippo.com/) to use the Shippo API. It's free to sign up, free to use the API. Only pay to print a live label, test labels are free. 
 
 ## Installation
 
-This library is distributed as a ruby gem, therefore youcan install it via adding the following line to your `Gemfile`:
+This library is distributed as a ruby gem, therefore you can install it via adding the following line to your `Gemfile`:
 
 ```
 gem 'shippo'
@@ -75,11 +32,14 @@ Or you can install the gem using the `gem` command:
 gem install shippo
 ```
 
-## Usage 
+## Usage
+
+> NOTE: examples below use the gem `awesome_print` to dump formatted objects and hashes to STDOUT. To be able to use the examples verbatum, please ensure you have this gem installed, or run: `gem install awesome_print --no-rdoc --no-ri`
 
+Below we demonstrate the most basic usage of the library:
 
 ```ruby
-require 'shippo/api'
+require 'shippo'
 
 # Setup your API token
 Shippo.api_key = 'aff988f77afa0fdfdfadf'  # not an actual valid token
@@ -117,9 +77,9 @@ params   = { object_purpose: 'PURCHASE',
                 distance_unit: :in,
                 weight:        2,
                 mass_unit:     :lb }
-} 
+}
 
-# Make our API call 
+# Make our API call
 @shipment = Shippo::Shipment.create(params)
 @shipment.success?
 # => true
@@ -131,7 +91,7 @@ params   = { object_purpose: 'PURCHASE',
 # => 'VALID'
 ```
 
-Let's take a quick look at what the `Address` object looks like:
+Let's take a quick look at what the `Shipment` object looks like:
 
 ```ruby
 require 'awesome_print'
@@ -140,10 +100,9 @@ ap @shipment
 #        "carrier_accounts" => [],
 #            "address_from" => "a704eada7494bb1be6184ef64b1646db",
 #              "address_to" => "92b43fbfa3641644beb32996042eb57a",
+#          "address_return" => "a1f64ba14b7e41b86a0446de4ebbd769",
 #                  "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",
@@ -162,10 +121,10 @@ ap @shipment
 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,
@@ -205,7 +164,7 @@ ap @shipment.rates_list.first
 #### 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`.
@@ -249,9 +208,9 @@ ap @shipment.object
 # }
 ```
 
-#### Validation 
+#### 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`. 
+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
 
@@ -264,11 +223,13 @@ export SHIPPO_TOKEN="<your token here>"
 bin/example
 ```
 
+NOTE: this environment variable is only used by the included `bin/example` script, and is not automatically used by the underlying client library.
+
 ## 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.
+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 supporting ruby 1.8 and 1.9.
 
-The intent, however, is to completely deprecate `shippo` gem in the near future.
+__Warning:__ Version 2 brings potential backwards incompatibility issues. Please be prepared to update your usages (if necessary) when you migrate. 
 
 ### If you are still using Ruby 1.8 or 1.9
 
@@ -276,7 +237,7 @@ If you are still using an older version of Ruby, please make sure to use the las
 
 ## Documentation
 
-Please see [https://goshippo.com/shipping-api/](https://goshippo.com/shipping-api/) for up-to-date documentation.
+Please see [https://goshippo.com/docs](https://goshippo.com/docs) for up-to-date documentation.
 
 For Ruby class documentation, please run the following rake task:
 
@@ -285,4 +246,26 @@ 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.
+This task will generate documentation using [Yard](http://yardoc.org/) and then open the browser with the generated index.html.
+
+## 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 discounted rates with the USPS and DHL Express. 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.
+
+## Supported Features
+
+The Shippo API provides in depth support of carrier and shipping functionalities. Here are just some of the features we support through the API:
+
+* Shipping rates & labels
+* Tracking for any shipment with just the tracking number
+* Batch label generation
+* Multi-piece shipments
+* Manifests and SCAN forms
+* Customs declaration and commercial invoicing
+* Address verification
+* Signature and adult signature confirmation
+* Consolidator support including:
+	* DHL eCommerce
+	* UPS Mail Innovations
+	* FedEx Smartpost
+* Additional services: cash-on-delivery, certified mail, delivery confirmation, and more.

data/bin/example

@@ -4,24 +4,55 @@
 #
 # License: MIT
 #
+# This example demonstrates how to purchase a label for a domestic US shipment.
+# Please set +SHIPPO_TOKEN+ in the environment before running it.
+#
+# You can also set +SHIPPO_DEBUG+ to see detailed printouts of objects returned.
+#
+#
+
 lib = File.expand_path('../../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 require 'bundler/setup'
-require 'shippo/api'
+require 'shippo'
 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
 
+# Simple wrapper class to help us print objects to the STDOUT
+class ExampleHelper
+  def self.log_operation(msg)
+    printf '%s', msg.blue
+    result = yield
+    puts 'OK'.bold.green
+    result
+  rescue Exception => e
+    puts 'ERROR'.bold.red
+    raise(e)
+  end
+
+  def self.dump_object(instance, msg = nil)
+    return unless ENV['SHIPPO_DEBUG']
+    sep
+    puts "#{msg.upcase.bold.green}:" if msg
+    puts "\#<#{instance.class.inspect.bold.blue}:0x#{instance.object_id.to_s(16).bold.yellow}> ⇒ "
+    ap instance
+    sep
+  end
+
+  def self.sep
+    puts '—' * (ENV['COLUMNS'] || 80)
+  end
+end
+
 # Create address_from object
-address_from      = {
+address_from = {
   :object_purpose => 'PURCHASE',
   :name           => 'Mr Hippo',
   :company        => 'Shippo',
@@ -35,7 +66,7 @@ address_from      = {
   :email          => 'support@goshippo.com' }
 
 # Create address_to object
-address_to        = {
+address_to   = {
   :object_purpose => 'PURCHASE',
   :name           => 'Mrs Hippo"',
   :company        => 'San Diego Zoo',
@@ -48,7 +79,7 @@ address_to        = {
   :email          => 'hippo@goshippo.com' }
 
 # Create parcel object
-parcel            = {
+parcel       = {
   :length        => 5,
   :width         => 2,
   :height        => 5,
@@ -61,10 +92,11 @@ hash = { :object_purpose => 'PURCHASE',
          :address_to     => address_to,
          :parcel         => parcel,
          :async          => false }
-puts 'Making first API call for shipment rates...'.blue.bold
 
 begin
-  shipment = Shippo::Shipment.create(hash)
+  shipment = ExampleHelper.log_operation 'Making first API call for shipment rates... ' do
+    Shippo::Shipment.create(hash)
+  end
   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)
@@ -90,23 +122,21 @@ 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)
+ExampleHelper.dump_object(rate, 'First rate returned')
 
-puts "Purchasing a #{rate} label!"
+transaction = ExampleHelper.log_operation 'Creating a label with the first rate in the list... ' do
+  # Purchase the desired rate (create a Transaction object)
+  Shippo::Transaction.create(rate: rate.id, async: false)
+end
+ExampleHelper.dump_object(transaction, 'Transaction object received')
 
-# 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
+    # noinspection RubyResolve
   transaction.label_url.bold.yellow }"
   puts "Tracking NO    : #{
-  # noinspection RubyResolve
+    # noinspection RubyResolve
   transaction.tracking_number.to_s.bold.yellow}"
 else
   puts 'Transaction ERROR'.bold.red

data/lib/shippo/api/transformers/list.rb

@@ -2,17 +2,18 @@ require 'active_support/inflector'
 module Shippo
   module API
     module Transformers
-      # List Transformer: if it finds a key named like 'rates_list' it converts it
-      # to another member 'rates' containing equivalent list of object instances of
-      # the corresponding type, in the example above – Shippo::Rate.
+      # List Transformer: if it finds a key mapped to an array, this transformer coerces each element
+      # into an appropriate model class – if available. As a result, return from, eg. +Shipment.create+
+      # will contain +rates+ key that will no longer be an array of hashes, but an array of +Shippo::Rate+
+      # instances.
       class List
         attr_accessor :h
 
-        # Matchers receive a key as a parameter, and they extract a candidate word to be
-        # tried in Coercing the values of the array to an object. For example, it could be
-        # "shipments" or "rates_list" or "items".
+        # +MATCHERS+ contains a list of procs that are used to try, in order, to convert a key
+        # mapped to an array of hashes, into a word that represents an existing model.
         #
-        # They are tried in order they are defined.
+        # Each matcher receives a key as a parameter, and (if matches) it extracts the candidate word to be
+        # attempted to +constantize+. For example, +rates_list+ matcher will return +rates+ as output.
 
         MATCHERS = [
           ->(key) {

data/lib/shippo/api/version.rb

@@ -1,5 +1,5 @@
 module Shippo
   module API
-    VERSION = '2.0.0'
+    VERSION = '2.0.1'
   end
 end

data/lib/shippo/model/carrieraccount.rb

@@ -1,5 +1,6 @@
 module Shippo
   class CarrierAccount < ::Shippo::API::Resource
     operations :list, :create, :update
+    url '/carrier_accounts'
   end
 end

data/shippo.gemspec

@@ -22,13 +22,13 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'hashie', '~> 3.4'
   spec.add_dependency 'activesupport', '~> 4'
   spec.add_dependency 'colored2'
-  spec.add_dependency 'require_dir'
+  spec.add_dependency 'require_dir', '~> 0.1'
+  spec.add_dependency 'awesome_print'
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'guard'
   spec.add_development_dependency 'guard-rspec'
   spec.add_development_dependency 'yard'
-  spec.add_development_dependency 'awesome_print'
   spec.add_development_dependency 'rspec', '~> 3.4'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shippo
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Shippo & Contributors
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-27 00:00:00.000000000 Z
+date: 2016-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -99,24 +99,24 @@ dependencies:
   name: require_dir
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.1'
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: awesome_print
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :development
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -124,7 +124,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -138,7 +138,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: guard
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -152,7 +152,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: guard-rspec
+  name: guard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -166,7 +166,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: yard
+  name: guard-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -180,7 +180,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: awesome_print
+  name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="