shippo 2.0.7 → 2.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7cf3a2a856cd835b2b6bd4b9dd581be7aa861c1d
-  data.tar.gz: 9e18225119fd342921378279dd15ef5827bfe4a0
+  metadata.gz: fd31fa476553d97988451c18460953d23d7f5aa6
+  data.tar.gz: f02f1f23ba6177ecc8b7db13ae3fdfb696a5684e
 SHA512:
-  metadata.gz: 8a4516e0260ac10b5e4437ccd3603f5f69384422a1ff9f57dd014e0b28dc20419ff455e2a334024c9d7482b5940197ef3ac6b9bf1ceb783633d8904dadbab043
-  data.tar.gz: d103a9d4cf47d126303892dac1281c84e3813525597eca4c8640bfa69f11f21e5ace1f81d5e6081adc963155ae8896e23dab1d7d29f2c8c0069d314eed7a6e4e
+  metadata.gz: be7319563465cddd71b074bd6562bbe5d34ea428d7ca027d48fec7798fd2019eab6798f2c08d4551129a00cb1dea26f669fd6a61a25e87a54379a9eafe340532
+  data.tar.gz: 308b45777bb9b65fb19b41cadab55883ac46689c0283525408212b03e4e04d0d57744b58b1fc86ed076aea1f8f5770d26bd311a34b1be1e4de476328d11af8cb

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+### 2.0.8 release, Feb 15th, 2017
+- Add Batch API with example code
+    - Creation
+    - Retrieval
+    - Adding shipments to Batch objects
+    - Removing shipments from Batch objects
+    - Purchasing
+- Add Track API with example code
+    - Retrieving tracking status of a shipment
+    - Registering a tracking webhook
+- Add mock tests using VCR (for Batch and Track API)
+    - https://github.com/vcr/vcr
+
 ### 2.0.7 release, Jan 2nd, 2017
 - Fixed bug preventing address validation
 - Removed trailing slash from base URL, added spec test to ensure this configuration
@@ -5,9 +18,11 @@
 - Updated basic shipment example to include how to access the Shippo object id
 ### 2.0.6 release, Nov 22nd, 2016
 - Fixed bug to send request with correct API version header
+
 #### 2.0.5 release, Oct 24th, 2016
  - Updated README.md
  - now possible to send API version
+ 
 #### 2.0.4 release, Oct 6th 2016
  - Rails5 Compatibility via relaxed dependencies
    - removing mime-types dependency

data/README.md

@@ -183,13 +183,17 @@ Shippo API returns several generalized fields for each valid resource, that bein
 
 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`.
+For this reason we are mapping `object_id` to `resource_id`, as soon as the hash is passed in to initialize `ApiObject`. This way `object_id` continues to be used as a ruby internal field, and can be accessed as expected:
 
-The following console output demonstrates many ways of accessing `object_` fields:
+> In the example below, `object_id` does not refer to any API field, and is a ruby internal field.
 
 ```ruby
 @shipment.object_id    # this is the Ruby object pointer
 # ⤷ 70206221831520  
+```
+To access the `"object_id"` field retrieved with the API, see the following session that highlights many ways of accessing `object_id` field:
+
+```ruby
 @shipment.resource_id  # this is the API id (note: deprecated accessor)
 # ⤷ 20f25e44b16b4051b6dd910cb66fd27b
 @shipment.object.id    # which is actually just this
@@ -198,7 +202,7 @@ The following console output demonstrates many ways of accessing `object_` field
 # ⤷ 20f25e44b16b4051b6dd910cb66fd27b
 ```
 
-And with the rest of the `object_` fields:
+Finally, here is how we access the rest of the `object_` fields:
 
 ``` ruby
 @shipment.object.owner    # this is whether 'object_owner' is stored

data/bin/batch_example

@@ -0,0 +1,211 @@
+#!/usr/bin/env ruby
+#
+# © 2016 Shippo, Inc.
+#
+# License: MIT
+#
+# This example demonstrates how to get the tracking status of a 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'
+require 'shippo/api/category'
+require 'shippo/exceptions/api_error'
+require 'awesome_print'
+require 'json'
+
+Shippo::API.token = ENV['SHIPPO_TOKEN']
+Hashie.logger = Logger.new(nil)
+
+# Simple wrapper class to help us print objects to the STDOUT
+class ExampleHelper
+  def self.log_operation(msg)
+    printf "%s", msg
+    result = yield
+    print "OK\n"
+    result
+  rescue Exception => e
+    raise(e)
+  end
+
+  def self.dump_object(instance, msg = nil)
+    return unless Shippo::API.debug?
+    sep
+    puts "#{msg.upcase}:" if msg
+    puts "\#<#{instance.class.inspect}:0x#{instance.object_id.to_s(16)}> ⇒ "
+    ap instance
+    sep
+    # See https://github.com/goshippo/shippo-ruby-client#resource-id-and-other-object-fields
+    puts "Shippo object id: #{instance.object.id}"
+    sep
+  end
+
+  def self.sep
+    puts '—' * (ENV['COLUMNS'] || 80)
+  end
+
+  # Retries up to 10 times to retrieve a valid
+  # Batch (which takes time to become 'VALID' from
+  # 'VALIDATING' after initially being created).
+  def self.retrieve_valid_batch(id)
+    retries = 10
+    retrieve = nil
+    until retries == 0 do
+      sleep 1
+      retrieve = Shippo::Batch::get(id)
+      break if retrieve[:object_status] == 'VALID'
+      retries -= 1
+    end
+    STDERR.puts 'Unable to retrieve VALID Batch object' unless retrieve
+    retrieve
+  end
+end
+
+# 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 }
+
+default_carrier_account = ENV['SHIPPO_TEST_CARRIER_ACCOUNT']
+if !default_carrier_account
+  STDERR.puts 'Please set your SHIPPO_TEST_CARRIER_ACCOUNT environment variable.'
+  STDERR.puts
+  STDERR.puts 'You can do this by setting it to your USPS carrier account object ID:
+
+  Steps
+  --------------------------------------------------------------
+  1. curl https://api.goshippo.com/carrier_accounts/ \
+    -H "Authorization: ShippoToken <TEST_API_TOKEN>"
+
+  2. Look for {"carrier": "usps"} and find its "object_id"
+
+  3. export SHIPPO_TEST_CARRIER_ACCOUNT=<USPS_CARRIER_OBJECT_ID>
+  --------------------------------------------------------------
+  '
+  STDERR.puts
+  exit 1
+end
+hash = { :default_carrier_account => default_carrier_account,
+         :default_servicelevel_token => 'usps_priority',
+         :label_filetype => 'ZPLII',
+         :metadata => 'BATCH #170',
+         :batch_shipments => [
+           {
+             :shipment => {
+               :object_purpose => 'PURCHASE',
+               :address_from   => address_from,
+               :address_to     => address_to,
+               :parcel         => parcel,
+               :async          => false
+             }
+           }
+         ]
+       }
+
+shipment_params = { :object_purpose => 'PURCHASE',
+                    :address_from   => address_from,
+                    :address_to     => address_to,
+                    :parcel         => parcel,
+                    :async          => false }
+
+begin
+  batch = ExampleHelper.log_operation 'Making first API call to create a batch...' do
+    Shippo::Batch.create(hash)
+  end
+
+  retrieve = ExampleHelper.log_operation 'Making API call to retrieve newly created batch...' do
+    ExampleHelper.retrieve_valid_batch(batch[:object_id])
+  end
+  puts "Batch status    : #{retrieve[:object_status]}"
+  puts "metadata        : #{retrieve[:metadata]}"
+  puts "Batch shipment count = #{retrieve[:batch_shipments][:count]}"
+  puts
+
+  shipment = ExampleHelper.log_operation 'Making API call to create a shipment... ' do
+    Shippo::Shipment.create(shipment_params)
+  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)
+  end
+
+  # Adding shipments
+  shipments = Array.new
+  shipments.push({"shipment" => shipment[:object_id]})
+  added = ExampleHelper.log_operation 'Making API call to add a new shipment to batch...' do
+    Shippo::Batch::add_shipment(retrieve[:object_id], shipments)
+  end
+  puts "Batch shipment count = #{added[:batch_shipments][:count]}"
+  puts
+
+  # Removing shipments
+  shipments_to_remove = Array.new
+  shipments_to_remove.push(added.batch_shipments.results[0][:object_id])
+  removed = ExampleHelper.log_operation 'Making API call to remove the new shipment from batch...' do
+    Shippo::Batch::remove_shipment(retrieve[:object_id], shipments_to_remove)
+  end
+  puts "Batch shipment count = #{removed[:batch_shipments][:count]}"
+  puts
+
+  # Purchasing a batch
+  purchase = ExampleHelper.log_operation 'Making API call to purchase a batch...' do
+    Shippo::Batch::purchase(retrieve[:object_id])
+  end
+  puts "Batch status = #{purchase[:object_status]}"
+  puts
+
+rescue Shippo::Exceptions::APIServerError => e
+  puts "Server returned an error:\n#{e}"
+  exit 3
+rescue Shippo::Exceptions::ConnectionError
+  puts 'Error connecting to remote host. Is your Internet working?'
+  exit 2
+rescue Shippo::Exceptions::AuthenticationError
+  if Shippo::API.token
+    puts "Token '#{Shippo::API.token}' does not appear to be valid."
+    puts 'Access denied.'
+  else
+    puts 'Please set authentication token in the environment:'
+    puts 'export SHIPPO_TOKEN="<your token here>"'
+    puts 'and re-run the example.'
+  end
+  exit 1
+end

data/bin/track_example

@@ -0,0 +1,131 @@
+#!/usr/bin/env ruby
+#
+# © 2016 Shippo, Inc.
+#
+# License: MIT
+#
+# This example demonstrates how to get the tracking status of a 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'
+require 'shippo/api/category'
+require 'shippo/exceptions/api_error'
+require 'awesome_print'
+require 'json'
+
+Shippo::API.token = ENV['SHIPPO_TOKEN']
+Hashie.logger = Logger.new(nil)
+
+# Simple wrapper class to help us print objects to the STDOUT
+class ExampleHelper
+  def self.log_operation(msg)
+    printf '%s', msg
+    result = yield
+    printf "OK\n"
+    result
+  rescue Exception => e
+    raise(e)
+  end
+
+  def self.dump_object(instance, msg = nil)
+    return unless Shippo::API.debug?
+    sep
+    puts "#{msg.upcase}:" if msg
+    puts "\#<#{instance.class.inspect}:0x#{instance.object_id.to_s(16)}> ⇒ "
+    ap instance
+    sep
+    # See https://github.com/goshippo/shippo-ruby-client#resource-id-and-other-object-fields
+    puts "Shippo object id: #{instance.object.id}"
+    sep
+  end
+
+  def self.sep
+    puts '—' * (ENV['COLUMNS'] || 80)
+  end
+end
+
+# 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 }
+
+begin
+  shipment = ExampleHelper.log_operation 'Making first API call for shipment rates...' do
+    Shippo::Shipment.create(hash)
+  end
+  track = ExampleHelper.log_operation 'Making API call to retrieve tracking status...' do
+    Shippo::Track.get(shipment[:object_id], 'usps')
+  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)
+  end
+rescue Shippo::Exceptions::APIServerError => e
+  puts "Server returned an error:\n#{e}"
+  exit 3
+rescue Shippo::Exceptions::ConnectionError
+  puts 'Error connecting to remote host. Is your Internet working?'
+  exit 2
+rescue Shippo::Exceptions::AuthenticationError
+  if Shippo::API.token
+    puts "Token '#{Shippo::API.token}' does not appear to be valid."
+    puts 'Access denied.'
+  else
+    puts 'Please set authentication token in the environment:'
+    puts 'export SHIPPO_TOKEN="<your token here>"'
+    puts 'and re-run the example.'
+  end
+  exit 1
+end
+
+if track
+  puts "Carrier         : #{track[:carrier]}"
+  puts "Tracking NO     : #{track[:tracking_number]}"
+else
+  puts 'Track ERROR'
+end

data/lib/shippo/api/api_object.rb

@@ -78,7 +78,7 @@ module Shippo
 
       # list of allowed properties, of a given type.
       PROPS_ID         = %i(id).freeze
-      PROPS_CATEG      = %i(state purpose source status).freeze
+      PROPS_CATEG      = %i(state purpose source status results).freeze
       PROPS_EMAIL      = %i(owner).freeze
       PROPS_TIMED      = %i(created updated).freeze
 

data/lib/shippo/api/operations/batch.rb

@@ -0,0 +1,38 @@
+module Shippo
+  module API
+    module Operations
+      module Batch
+        # Retrieves a Batch by its ID
+        # @param [String] id The ID of the Batch object
+        # @param [Hash] params Optional params tacked onto the URL as URI parameters
+        def get(id, params={})
+          response = Shippo::API.get("#{url}/#{CGI.escape(id)}", params)
+          self.from(response)
+        end
+
+        # Adds a new shipment to a batch object
+        # @param [String] id The ID of the Batch object
+        # @param [Array] shipments Array of shipment objects to be added
+        def add_shipment(id, shipments=[])
+          response = Shippo::API.post("#{url}/#{CGI.escape(id)}/add_shipments", shipments)
+          self.from(response)
+        end
+
+        # Removes an existing shipment from a batch object
+        # @param [String] id The ID of the Batch object
+        # @param [Array] shipment_ids Array of shipment IDs to be removed
+        def remove_shipment(id, shipment_ids=[])
+          response = Shippo::API.post("#{url}/#{CGI.escape(id)}/remove_shipments", shipment_ids)
+          self.from(response)
+        end
+
+        # Purchases an existing batch
+        # @param [String] id The ID of the Batch object
+        def purchase(id)
+          response = Shippo::API.post("#{url}/#{CGI.escape(id)}/purchase")
+          self.from(response)
+        end
+      end
+    end
+  end
+end

data/lib/shippo/api/operations/track.rb

@@ -0,0 +1,15 @@
+module Shippo
+  module API
+    module Operations
+      module Track
+        # Retrieves tracking status of a shipment
+        # @param [Fixnum] id Database ID of the shipment to be received
+        # @param [String] carrier The carrier of the item to be received
+        def get(id, carrier)
+          response = Shippo::API.get("#{url}/#{CGI.escape(carrier)}/#{CGI.escape(id)}/")
+          self.from(response)
+        end
+      end
+    end
+  end
+end

data/lib/shippo/api/resource.rb

@@ -19,6 +19,8 @@ module Shippo
       include Enumerable
       extend Forwardable
 
+      disable_warnings
+
       def self.object_properties
         Shippo::API::ApiObject::PROPS
       end
@@ -62,7 +64,7 @@ module Shippo
 
       # As a Hashie::Mash subclass, Resource can initialize from another hash
       def initialize(*args)
-        if args.first.is_a?(Fixnum) or
+        if args.first.is_a?(Integer) or
           (args.first.is_a?(String) && args.first =~ /^[0-9A-Fa-f]+$/)
           self.id = args.first
         elsif args.first.respond_to?(:keys)

data/lib/shippo/api/version.rb

@@ -1,5 +1,5 @@
 module Shippo
   module API
-    VERSION = '2.0.7'
+    VERSION = '2.0.8'
   end
 end

data/lib/shippo/model/batch.rb

@@ -0,0 +1,5 @@
+module Shippo
+  class Batch < ::Shippo::API::Resource
+    operations :create, :batch
+  end
+end

data/lib/shippo/model/track.rb

@@ -0,0 +1,5 @@
+module Shippo
+  class Track < ::Shippo::API::Resource
+    operations :create, :track
+  end
+end

data/shippo.gemspec

@@ -28,4 +28,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'guard-rspec'
   spec.add_development_dependency 'yard'
   spec.add_development_dependency 'rspec', '~> 3.4'
+  spec.add_development_dependency 'webmock', '~> 2.1'
+  spec.add_development_dependency 'vcr', '~> 3.0', '>= 3.0.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shippo
 version: !ruby/object:Gem::Version
-  version: 2.0.7
+  version: 2.0.8
 platform: ruby
 authors:
 - Shippo & Contributors
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-01-24 00:00:00.000000000 Z
+date: 2017-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -165,6 +165,40 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.3
 description: A gem for connecting with over 20 shipping carriers and consolidators
   via a single integration using Shippo API. Support for shipping rates, buying and
   printing labels, tracking as well as some carrier specific functionality such as
@@ -190,7 +224,9 @@ files:
 - Rakefile
 - bin/address_validation_example
 - bin/basic_shipment_example
+- bin/batch_example
 - bin/console
+- bin/track_example
 - lib/shippo.rb
 - lib/shippo/api.rb
 - lib/shippo/api/api_object.rb
@@ -204,9 +240,11 @@ files:
 - lib/shippo/api/extend/transformers.rb
 - lib/shippo/api/extend/url.rb
 - lib/shippo/api/operations.rb
+- lib/shippo/api/operations/batch.rb
 - lib/shippo/api/operations/create.rb
 - lib/shippo/api/operations/list.rb
 - lib/shippo/api/operations/rates.rb
+- lib/shippo/api/operations/track.rb
 - lib/shippo/api/operations/update.rb
 - lib/shippo/api/operations/validate.rb
 - lib/shippo/api/request.rb
@@ -218,6 +256,7 @@ files:
 - lib/shippo/exceptions/api_server_error.rb
 - lib/shippo/exceptions/error.rb
 - lib/shippo/model/address.rb
+- lib/shippo/model/batch.rb
 - lib/shippo/model/carrieraccount.rb
 - lib/shippo/model/customs_declaration.rb
 - lib/shippo/model/customs_item.rb
@@ -226,6 +265,7 @@ files:
 - lib/shippo/model/rate.rb
 - lib/shippo/model/refund.rb
 - lib/shippo/model/shipment.rb
+- lib/shippo/model/track.rb
 - lib/shippo/model/transaction.rb
 - lib/shippo/tasks/shippo.rb
 - shippo.gemspec
@@ -250,7 +290,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.9
+rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
 summary: API client for Shippo® APIs. Shippo helps you connect with multiple carriers