pbshipping 1.0.0

data/test/ts_all_tests.rb

@@ -0,0 +1,21 @@
+#
+# Copyright 2016 Pitney Bowes Inc.
+#
+# Licensed under the MIT License (the "License"); you may not use this file 
+# except in compliance with the License. You may obtain a copy of the License 
+# in the LICENSE file or at 
+#     https://opensource.org/licenses/MIT
+#
+# Unless required by applicable law or agreed to in writing, software 
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+# See the License for the specific language governing permissions and 
+# limitations under the License.
+#
+# File: ts_all_tests.rb
+# Description: running all available unit tests
+# 
+
+require "test/unit"
+Dir["./tc_*.rb"].each {|file| require file }
+

data/tutorial.rb

@@ -0,0 +1,464 @@
+#
+# Copyright 2016 Pitney Bowes Inc.
+#
+# Licensed under the MIT License (the "License"); you may not use this file 
+# except in compliance with the License. You may obtain a copy of the License 
+# in the LICENSE file or at 
+#     https://opensource.org/licenses/MIT
+#
+# Unless required by applicable law or agreed to in writing, software 
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+# See the License for the specific language governing permissions and 
+# limitations under the License.
+#
+# File: tutorial.rb
+# Description: a tutorial example exercising the shipping apis
+# 
+
+# Tutorial
+require 'optparse'
+require "json"
+require 'pbshipping'
+
+module PBShippingTutorial
+
+  @api_key = nil
+  @api_secret = nil
+  @dev_id = nil
+  @merchant_email = nil
+  @merchant = nil
+  @from_addr = nil
+  @to_addr = nil
+  @shipment = nil
+  @shipment_orig_tx_id = nil
+  @tracking = nil
+  @manifest = nil
+  @manifest_orig_tx_id = nil
+  @auth_obj = nil
+
+  @my_bulk_merchant_addr = { 
+    :addressLines => ["27 Waterview Drive"], 
+    :cityTown => "Shelton", 
+    :stateProvince => "Connecticut", 
+    :postalCode => "06484", 
+    :countryCode => "US", 
+    :company => "Pitney Bowes", 
+    :name => "John Doe", 
+    :email => "dummy@pbshipping.com", 
+    :phone => "203-792-1600", 
+    :residential => false 
+  }
+
+  @my_origin_addr = {
+    :addressLines => ["37 Executive Drive"],
+    :cityTown => "Danbury",
+    :stateProvince => "Connecticut",
+    :postalCode => "06810",
+    :countryCode => "US"
+  }
+
+  @my_dest_addr = {
+    :addressLines => ["27 Waterview Drive"], 
+    :cityTown => "Shelton",
+    :stateProvince => "Connecticut",
+    :postalCode => "06484",
+    :countryCode => "US"
+  }
+  
+  @my_parcel = {
+    :weight => {
+        :unitOfMeasurement => "OZ",
+        :weight => 1
+    },
+    :dimension => {
+        :unitOfMeasurement => "IN",
+        :length => 6,
+        :width => 0.25,
+        :height => 4,
+        :irregularParcelGirth => 0.002
+    }
+  }
+
+  @my_rate_request_carrier_usps = {
+    :carrier => "usps",
+    :serviceId => "PM",
+    :parcelType => "PKG",
+    :specialServices => [
+        {
+            :specialServiceId => "Ins",
+            :inputParameters => [
+                {
+                    :name => "INPUT_VALUE",
+                    :value => "50"
+                }
+             ]
+        },
+        {
+            :specialServiceId => "DelCon",
+            :inputParameters => [
+                {
+                    :name => "INPUT_VALUE",
+                    :value => "0"
+                }
+             ]
+        }
+    ],
+    :inductionPostalCode => "06810"
+  }
+
+  @my_shipment_document = {
+    :type => "SHIPPING_LABEL",
+    :contentType => "URL",
+    :size => "DOC_8X11",
+    :fileFormat => "PDF",
+    :printDialogOption => "NO_PRINT_DIALOG"
+  }
+
+  # use the current timestamp to generate a transaction id
+  def self.get_pb_tx_id()
+    
+    Time.now().to_i.to_s
+  end
+
+  # obtain authentication, developer, and merchant infomration from 
+  # command line  
+  def self.initialize_info() 
+
+    options = {}
+    
+    # try environment variables ...    
+    if ENV["PBSHIPPING_KEY"] != nil 
+      options[:key] = ENV["PBSHIPPING_KEY"]
+    end
+    if ENV["PBSHIPPING_SECRET"] != nil 
+      options[:secret] = ENV["PBSHIPPING_SECRET"]
+    end
+    if ENV["PBSHIPPING_DEVID"] != nil 
+      options[:devid] = ENV["PBSHIPPING_DEVID"]
+    end
+    if ENV["PBSHIPPING_MERCHANT"] != nil 
+      options[:merchant] = ENV["PBSHIPPING_MERCHANT"]
+    end
+            
+    optparse = OptionParser.new do |opts|
+      opts.banner = "Usage: tutorial.rb [options]"
+      # command line arguments overwrite environment variables
+      opts.on('-h', '--help', 'Display help') do
+        puts opts
+        exit
+      end
+      opts.on('-k', '--key API_KEY', 'API key for authentication') do |api_key|
+        options[:key] = api_key
+      end
+      opts.on('-s', '--secret API_SECRET', 'API secret for authentication') do |api_secret|
+        options[:secret] = api_secret
+      end        
+      opts.on('-d', '--devid DEVELOPER_ID', 'Pitney Bowes Developer ID') do |dev_id|
+        options[:devid] = dev_id
+      end          
+      opts.on('-m', '--merchant MERCHANT_EMAIL', 'Merchant email') do |merchant_email|
+        options[:merchant] = merchant_email
+      end    
+    end  
+    
+    begin
+      optparse.parse!
+      mandatory = [:key, :secret, :devid, :merchant]
+      missing = mandatory.select{ |param| options[param].nil? }
+      unless missing.empty?
+        puts "Missing options: #{missing.join(', ')}"
+        puts optparse
+        exit
+      end
+      @api_key = options[:key]
+      @api_secret = options[:secret]
+      @dev_id = options[:devid]
+      @merchant_email = options[:merchant]
+    rescue OptionParser::InvalidOption, OptionParser::MissingArgument
+      puts $!.to_s
+      puts optparse
+      exit
+    end
+  end
+
+  # choose sandbox or production pitney bowes shipping api server
+  def self.choose_environment()
+    
+    puts "Choose the sandbox environment ..."
+    PBShipping::configuration[:is_production] = false
+  end
+      
+  # authenticate and obtain the authentication object for subsequent use
+  # underlying API: POST /oauth/token  
+  def self.authenticate()
+    
+    puts 'Authenticating ...'
+    @auth_obj = PBShipping::AuthenticationToken.new(@api_key, @api_secret)    
+  end
+
+  # return the list of supported countries 
+  # underlying API: GET /countries
+  def self.check_carrier_supported_countries()
+    
+    puts "Querying for supported countries of USPS carrier ..."
+    country_list = PBShipping::Carrier.getCountriesForCarrier(@auth_obj, "usps", "US")
+    n = country_list.length()
+    puts "   number of supported countries is " + n.to_s
+    puts "   one example is " + country_list[n/3].countryName
+  end
+ 
+  # managing merchant account under individual account mode
+  # underlying API: GET /developers/{developerId}/merchants/emails/{emailId}/
+  #                 GET /ledger/accounts/{accountNumber}/balance   
+  def self.manage_individual_mode_merchant()
+    
+    # querying for merchant information
+    puts "Managing merchant (individual account mode) ..."
+    @developer = PBShipping::Developer.new( { :developerId => @dev_id } )
+    @merchant = @developer.registerMerchantIndividualAccount(
+      @auth_obj, @merchant_email)
+    merchant_account_number = @merchant.paymentAccountNumber
+    
+    # querying for merchant account balance
+    balance = PBShipping::Account.getBalanceByAccountNumber(
+      @auth_obj, merchant_account_number)
+    puts "   merchant full name is " + @merchant.fullName
+    puts "   shipper id is " + @merchant.postalReportingNumber
+    puts "   payment account number is " + merchant_account_number
+    puts "   current balance is " + balance.currencyCode + " " + \
+                                    balance.balance.to_s   
+  end
+
+  # managing merchant account under bulk account mode
+  # underlying API: POST /developers/{developerId}/merchants/registration  
+  def self.manage_bulk_mode_merchant()
+    
+    puts "Managing merchant (bulk account mode) ..."
+    @developer = PBShipping::Developer.new( { :developerId => @dev_id } )
+    merchant_addr = PBShipping::Address.new(@my_bulk_merchant_addr)
+    merchant = @developer.registerMerchantBulkAccount(@auth_obj, merchant_addr)
+    puts merchant
+  end
+
+  # verifying addresses
+  # underlying API: POST /addresses/verify  
+  def self.verify_addresses()
+    
+    puts "Verifying origin and destination addresses ... "
+    @from_addr = PBShipping::Address.new(@my_origin_addr)
+    @from_addr.verify(@auth_obj, false)
+    if @from_addr.status.downcase == "validated_changed"
+      puts "   origin address cleansed, addressLine is " + \
+           @from_addr.addressLines[0]
+    end
+    
+    @to_addr = PBShipping::Address.new(@my_dest_addr)
+    @to_addr.verify(@auth_obj, false)
+    if @to_addr.status.downcase == "validated_changed"
+      puts "   destination address cleansed, addressLine is " + \
+           @to_addr.addressLines[0]
+    end
+  end
+
+  # querying rates to prepare a shipment
+  # underlying API: POST /rates
+  def self.prepare_shipment()
+
+    puts "Preparing shipment and checking for shipment rates ..."
+    rates = [ PBShipping::Rate.new(@my_rate_request_carrier_usps) ]
+    parcel = PBShipping::Parcel.new(@my_parcel)     
+    documents = [ PBShipping::Document.new(@my_shipment_document)]
+    shipmentOptions = [
+      PBShipping::ShipmentOptions.new({
+        :name => "SHIPPER_ID", 
+        :value => @merchant.postalReportingNumber
+      }),
+      PBShipping::ShipmentOptions.new({
+        :name => "ADD_TO_MANIFEST", 
+        :value => true 
+      })
+    ]              
+    @shipment = PBShipping::Shipment.new({
+      :fromAddress => @from_addr, 
+      :toAddress => @to_addr,
+      :parcel => parcel, 
+      :rates => rates,
+      :documents => documents,
+      :shipmentOptions => shipmentOptions
+    })
+    @shipment.rates = @shipment.getRates(@auth_obj, get_pb_tx_id(), true)  
+    puts "   total carrier charge: " + @shipment.rates[0][:totalCarrierCharge].to_s
+  end
+
+  # submit a shipment creation request and purchase a shipment label
+  # underlying API: POST /shipments
+  def self.create_and_purchase_shipment()
+
+    puts "Creating shipment and purchasing label ..."
+    @shipment_orig_tx_id = get_pb_tx_id()
+    @shipment.createAndPurchase(@auth_obj, @shipment_orig_tx_id, true)
+  
+    puts "   parcel tracking number is " + @shipment.parcelTrackingNumber
+    for doc in @shipment.documents
+      puts "   document type is " + doc[:type]
+      if doc[:contentType] == "URL" && doc.key?(:contents)
+        puts "   document URL is " + doc[:contents]
+      end
+    end  
+  end
+
+  # reprint a shipment label
+  # underlying API: GET /shipments/{shipmentId}
+  def self.reprint_shipment()
+    
+    puts "Reprinting label ..."
+    @shipment.reprintLabel(@auth_obj)
+    for doc in @shipment.documents
+      if doc[:contentType] == "URL" && doc.key?(:contents)
+        puts "   document URL is " + doc[:contents]
+      end
+    end   
+  end     
+
+  # retry a shipment purchase request 
+  # underlying API: GET /shipments?originalTransactionId    
+  def self.retry_shipment()
+    
+    puts "Retrying shipment order ..."
+    @shipment.retry(@auth_obj, get_pb_tx_id(), @shipment_orig_tx_id) 
+  end
+  
+  # submit a shipment cancellation request
+  # underlying API: DELETE /shipments/{shipmentId}
+  def self.cancel_shipment()
+    
+    puts "Canceling shipment order ..." 
+    cancel_result = @shipment.cancel(@auth_obj, @shipment_orig_tx_id, 
+                                     @shipment.rates[0].carrier)
+    puts "   status: " + cancel_result["status"]
+  end
+
+  # create a manifest
+  # underlying API: POST /manifests
+  def self.create_manifest()
+
+    puts "Creating manifest ..."
+    @manifest = PBShipping::Manifest.new( {
+      :carrier => @tracking.carrier, 
+      :submissionDate => Time.now.utc.strftime("%Y-%m-%d"),
+      :parcelTrackingNumbers => [@shipment.parcelTrackingNumber],
+      :fromAddress => @shipment.fromAddress
+    } )
+    @manifest_orig_tx_id = get_pb_tx_id()
+    @manifest.create(@auth_obj, @manifest_orig_tx_id)
+    puts "   manifest tracking number is " + @manifest.manifestTrackingNumber
+    puts "   manifest id is " + @manifest.manifestId
+  end
+
+# reputs a manifest
+# underlying API: GET /manifests/{manifestId}
+  def self.reprint_manifest()
+    
+    puts "Repringing manifest ..."
+    
+    @manifest.reprint(@auth_obj)
+    puts "   reprinted manifestId is " + @manifest.manifestId
+  end
+
+  # retry a mainfest
+  # Underly API: GET /manifests
+  def self.retry_manifest()
+    
+    puts "Retrying manifest request ..."
+    @manifest.retry(@auth_obj, get_pb_tx_id(),  @manifest_orig_tx_id)    
+    puts "   manifest id is " + @manifest.manifestId
+  end
+
+  # get tracking information
+  # Underlying API: GET /tracking/{trackingNumber}
+  def self.get_tracking_update()
+        
+    puts "Get tracking status ..."
+    @tracking = PBShipping::Tracking.new( { :trackingNumber => @shipment.parcelTrackingNumber } )
+    begin
+        @tracking.updateStatus(@auth_obj)        
+    rescue => e
+      case e
+      when PBShipping::ApiError 
+        if PBShipping::configuration[:is_production] == false
+          puts "   no tracking information in sandbox environment"
+          return
+        end
+        raise e
+      end
+    end
+    puts "   status = " + _tracking.status
+  end
+
+  # querying for a transaction report
+  # Underlying API: GET /
+  def self.get_transaction_report()
+    
+    puts "Retrieving transaction report ..."
+    params = {}
+    params[:merchantId] = @merchant.postalReportingNumber
+    report = PBShipping::Developer.new({:developerId => @dev_id}).getTransactionReport(
+      @auth_obj, params)
+    puts "   First few entries ..."
+    i = 0
+    for next_row in report.content
+      txn = PBShipping::TransactionDetails.new(next_row)
+      txn_detail = "      id: " + txn.transactionId
+      txn_detail += " type: " + txn.transactionType
+      puts txn_detail
+    end
+  end
+  
+  # navgiate through different steps in shipping workflow                              
+  def self.shipping_workflow()
+    
+    begin
+
+      initialize_info()
+      
+      choose_environment()
+      
+      authenticate()
+      
+      check_carrier_supported_countries()
+      
+      # choose appropriate calls for individual or bulk account mode
+      manage_individual_mode_merchant()
+      #manage_bulk_mode_merchant()
+      
+      verify_addresses()
+      
+      prepare_shipment()
+      create_and_purchase_shipment()
+      reprint_shipment()
+      retry_shipment()
+      
+      get_tracking_update()
+
+      create_manifest()
+      reprint_manifest()
+      retry_manifest()
+      
+      get_transaction_report()
+      
+      cancel_shipment()
+        
+    rescue => e
+      if e.is_a?(PBShipping::ApiError) && e.error_info != nil
+        puts e.message
+        puts e.error_info
+      else
+        puts "hit an exception"
+        puts e
+      end
+    end
+  end
+end
+
+PBShippingTutorial::shipping_workflow()