pbshipping 1.0.0

data/lib/pbshipping/tracking.rb

@@ -0,0 +1,53 @@
+#
+# 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: tracking.rb
+# Description: shipment tracking functions
+# 
+
+module PBShipping
+  class Tracking < ShippingApiResource
+    
+    #
+    # TRACKING
+    # API: GET /tracking/{trackingNumber}
+    # API signature: get/tracking/...
+    #
+    # Shipment labels that are printed using the Pitney Bowes APIs are 
+    # automatically tracked and their package status can be easily retrieved 
+    # using this implementation of the GET operation.
+    #    
+    def updateStatus(auth_obj) 
+      if self.key?(:trackingNumber) == false
+        raise MissingResourceAttribute.new(:trackingNumber)
+      end
+      if self.key?(:packageIdentifierType) == false
+        self[:packageIdentifierType] = "TrackingNumber"
+      end
+      if self.key?(:carrier) == false
+        self[:carrier] = "USPS"
+      end
+      params = {
+        :carrier => self[:carrier],
+        :packageIdentifierType => self[:packageIdentifierType]
+      }
+      api_sig = "get/tracking/..."
+      api_version = PBShipping::get_api_version(api_sig)
+      api_path = "/tracking/" + self[:trackingNumber]
+      json_resp = PBShipping::api_request(
+        auth_obj, :get, api_version, api_path, {}, params, {})
+      self.update(json_resp)
+    end
+  end
+end

data/lib/pbshipping/transactiondetails.rb

@@ -0,0 +1,22 @@
+#
+# 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: transactiondetails.rb
+# Description: transaction detail objects
+# 
+
+module PBShipping
+  class TransactionDetails < ShippingApiResource
+  end
+end

data/lib/pbshipping/version.rb

@@ -0,0 +1,3 @@
+module PBShipping
+  VERSION = "1.0.0"
+end

data/test/tc_address.rb

@@ -0,0 +1,46 @@
+#
+# 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: tc_address.rb
+# Description: unit test for address verification
+# 
+
+require "test/unit"
+require "pbshipping"
+require_relative "test_util"
+
+class TestAddress < Test::Unit::TestCase
+
+  def setup
+    @auth_obj = PBShipping::AuthenticationToken.new(
+      PBShippingTestUtil::api_key, PBShippingTestUtil::api_secret) 
+  end
+
+  def teardown
+  end
+
+  def test_address
+    puts "Testing get countries call ..."
+    usps_carrier = PBShipping::Carrier.new({:name => "usps"})
+    usps_carrier.getCountries(@auth_obj, "US")  
+    
+    puts "Testing address verification ..." 
+    # expect the address is cleansed and changed
+    address = PBShipping::Address.new(PBShippingTestUtil::my_origin_addr);
+    address.verify(@auth_obj, false)
+    assert_equal(address[:status].downcase, "validated_changed")
+  
+  end
+
+end

data/test/tc_manifest.rb

@@ -0,0 +1,69 @@
+#
+# 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: tc_manifest.rb
+# Description: unit test for manifest manipulation
+# 
+
+require "test/unit"
+require "pbshipping"
+
+class TestManifest < Test::Unit::TestCase
+
+  def setup
+    @auth_obj = PBShipping::AuthenticationToken.new(
+      PBShippingTestUtil::api_key, PBShippingTestUtil::api_secret)
+    @developer = PBShippingTestUtil::setup_developer(@auth_obj)    
+    merchant, @acct_num = PBShippingTestUtil::setup_merchant(
+      @auth_obj, @developer) 
+    @shipper_id = merchant.postalReportingNumber
+                           
+  end
+
+  def teardown 
+  end
+
+  def test_manifest
+    
+    shipment1, txid1 = PBShippingTestUtil::create_single_shipment(
+      @auth_obj, @developer, @shipper_id)
+    shipment2, txid2 = PBShippingTestUtil::create_single_shipment(
+      @auth_obj, @developer, @shipper_id)      
+      
+    carrier = PBShippingTestUtil::my_rate_request_carrier_usps[:carrier]
+    trk_nums = [shipment1.parcelTrackingNumber, 
+                shipment2.parcelTrackingNumber]
+                
+    manifest = PBShipping::Manifest.new( {
+      :carrier => carrier, 
+      :submissionDate => Time.now.utc.strftime("%Y-%m-%d"),
+      :parcelTrackingNumbers => trk_nums,
+      :fromAddress => shipment1.fromAddress
+    } )                
+
+    puts "Testing manifest creation ..."       
+    original_txid = PBShippingTestUtil::get_pb_tx_id()
+    manifest.create(@auth_obj, original_txid)
+    assert_equal(manifest.key?(:manifestId), true)
+                        
+    puts "Testing reprint manifest ..."
+    manifest.reprint(@auth_obj)
+        
+    puts "Testing retry manifest ..."
+    txid = PBShippingTestUtil::get_pb_tx_id()
+    manifest.retry(@auth_obj, txid, original_txid)
+    
+  end
+
+end

data/test/tc_merchant.rb

@@ -0,0 +1,44 @@
+#
+# 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: tc_merchant.rb
+# Description: unit test for merchant account query and registration
+# 
+
+require "test/unit"
+require "pbshipping"
+require_relative "test_util"
+
+class TestMerchant < Test::Unit::TestCase
+
+  def setup
+    @auth_obj = PBShipping::AuthenticationToken.new(
+      PBShippingTestUtil::api_key, PBShippingTestUtil::api_secret) 
+    puts ""      
+  end
+
+  def teardown
+  end
+
+  def test_Merchant
+    developer = PBShippingTestUtil::setup_developer(@auth_obj)
+ 
+    puts "Testing merchant registration ..."
+    merchant, acct_num = PBShippingTestUtil::setup_merchant(@auth_obj, developer)
+
+    puts "Testing account balance query ..."    
+    balance = PBShipping::Account.getBalanceByAccountNumber(@auth_obj, acct_num)  
+  end
+
+end

data/test/tc_shipment.rb

@@ -0,0 +1,89 @@
+#
+# 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: tc_shipment.rb
+# Description: unit test for shipment creation and management
+# 
+
+require "test/unit"
+require "pbshipping"
+
+class TestShipment < Test::Unit::TestCase
+
+  def setup
+    @auth_obj = PBShipping::AuthenticationToken.new(
+      PBShippingTestUtil::api_key, PBShippingTestUtil::api_secret)
+    @developer = PBShippingTestUtil::setup_developer(@auth_obj)
+    merchant, @acct_num = PBShippingTestUtil::setup_merchant(
+      @auth_obj, @developer) 
+    @shipper_id = merchant.postalReportingNumber
+  end
+
+  def teardown
+
+  end
+
+  def test_shipment
+ 
+    puts "Testing rate query and purchasing shipment label ..."
+    
+    start_balance = PBShipping::Account.getBalanceByAccountNumber(
+      @auth_obj, @acct_num)  
+    PBShippingTestUtil::check_shipment_rate(@auth_obj, @developer)
+    shipment, orig_txid = PBShippingTestUtil::create_single_shipment(
+      @auth_obj, @developer, @shipper_id)  
+    end_balance = PBShipping::Account.getBalanceByAccountNumber(
+      @auth_obj, @acct_num)     
+      
+    assert_equal(shipment.key?(:shipmentId), true)
+    assert_equal(PBShippingTestUtil::verify_ledger_balance_after_txn(
+      shipment, start_balance, end_balance), true)
+
+    puts "Testing 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] == true
+          raise e
+        elsif e.error_info.length < 1 
+          raise e
+        elsif e.error_info[0][:errorCode] != "PB-TRKPKG-ERR-7600"
+          raise e
+        else
+          puts "   no tracking information in sandbox environment"          
+        end
+      else
+        raise e
+      end 
+    end
+    
+    puts "Testing reprint shipment label ..."
+    shipment.reprintLabel(@auth_obj)
+    
+    puts "Testing retry shipment ..."
+    txid = PBShippingTestUtil::get_pb_tx_id()
+    shipment.retry(@auth_obj, txid, orig_txid) 
+                                                                             
+    puts "Testing canceling shipment ..."     
+    cancel_result = shipment.cancel(@auth_obj, orig_txid, 
+      shipment.rates[0].carrier)
+    assert_equal(cancel_result.key?(:status), true)
+    
+  end
+
+end

data/test/tc_transactionreport.rb

@@ -0,0 +1,93 @@
+#
+# 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: tc_transactionreport.rb
+# Description: unit test for querying for transaction history
+# 
+
+require 'bigdecimal'
+require "test/unit"
+require "pbshipping"
+require_relative "test_util"
+
+class TestTransactionReport < Test::Unit::TestCase
+
+  def setup
+    @auth_obj = PBShipping::AuthenticationToken.new(
+      PBShippingTestUtil::api_key, PBShippingTestUtil::api_secret) 
+    @developer = PBShippingTestUtil::setup_developer(@auth_obj)
+    merchant, acct_num = PBShippingTestUtil::setup_merchant(
+      @auth_obj, @developer)   
+    @shipper_id = merchant.postalReportingNumber  
+  end
+
+  def teardown
+  end
+  
+  def verifyAndPrintReport(report, query)
+    puts "  Total matching records = " + report.totalElements.to_s
+    puts "  Total number of pages = " + report.totalPages.to_s
+    puts "  Current page number is " + report.number.to_s
+    puts "  Page size is " + report.size.to_s
+    puts "  Sort by " + report[:sort][0][:property]
+
+    if report[:sort][0][:ascending] == true
+      sort_dir = "asc"
+    else
+      sort_dir = "desc"
+    end
+    sort_info = report[:sort][0][:property] + "," + sort_dir
+    assert_equal(sort_info, query[:sort])
+    
+    rate_benchmark = PBShippingTestUtil::check_shipment_rate(
+      @auth_obj, @developer)
+
+    for next_row in report.content
+            txn = PBShipping::TransactionDetails.new(next_row)
+            
+            if (txn.transactionType.include?("POSTAL PRINT"))
+              assert_equal(BigDecimal(txn.developerRateAmount, 3), BigDecimal(rate_benchmark, 3))
+            end
+
+            txn_detail = "      timestamp: " + txn.transactionDateTime
+            txn_detail += " txid: " + txn.transactionId
+            txn_detail += " type: " + txn.transactionType
+            txn_detail += " rate: " + txn.developerRateAmount.to_s
+            txn_detail += " balance: " + txn.shipperPostagePaymentAccountBalance.to_s
+            puts txn_detail  
+    end
+  end
+
+  def test_trasnsactionreport
+    puts "Testing get transaction report  ..."
+    
+    # limit to past 28 days 
+    time_now = Time.now.utc
+    seven_days_ago = time_now - 28 * 60 * 60 * 24
+    query = {:fromDate => seven_days_ago.iso8601, :toDate => time_now.iso8601}
+    # limit to transactions originating from this test suite
+    query[:transactionId] = "%%" + PBShippingTestUtil::test_suite_txid_prefix  + "%%"   
+    # limit to test suite merchant
+    query[:merchantId] = @shipper_id
+    # sort according to transaction id in descending order
+    query[:sort] = "transactionId,desc"
+
+    # paging control can be configured through these parameters           
+    # query[:page] = 0 # control the page to query for 
+    # query[:size] = 20 # control the page size     
+    report = @developer.getTransactionReport(@auth_obj, query)
+    verifyAndPrintReport(report, query)  
+  end
+
+end

data/test/test_util.rb

@@ -0,0 +1,222 @@
+#
+# 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: test_util.rb
+# Description: helper classes and functions supporting unit test
+# 
+
+require 'bigdecimal'
+
+module PBShippingTestUtil
+ 
+ @api_key = ENV["PBSHIPPING_KEY"]
+ @api_secret = ENV["PBSHIPPING_SECRET"]
+ @dev_id = ENV["PBSHIPPING_DEVID"]
+ @merchant_email = ENV["PBSHIPPING_MERCHANT"]
+ 
+ @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"
+  }
+
+  # this helps to identify transactions originating from the test suite
+  @test_suite_txid_prefix = "KYCB"
+  
+  class << self
+    attr_accessor :api_key, :api_secret, :dev_id, :merchant_email
+    attr_accessor :my_bulk_merchant_addr, :my_origin_addr, :my_dest_addr
+    attr_accessor :my_parcel, :my_rate_request_carrier_usps, :my_shipment_document
+    attr_accessor :test_suite_txid_prefix
+  end
+   
+  def self.get_pb_tx_id()
+    return @test_suite_txid_prefix + Time.now.utc.strftime("%Y%m%d%H%M%S%6N")
+  end
+
+  def self.setup_developer(auth_obj)
+    developer = PBShipping::Developer.new(
+      { :developerId => PBShippingTestUtil::dev_id} )
+    developer.refresh(auth_obj)  
+    return developer  
+  end
+  
+  def self.setup_merchant(auth_obj, developer)
+    if developer.bulkMode == false
+      merchant = developer.registerMerchantIndividualAccount(
+        auth_obj, @merchant_email)
+      acct_num = merchant.paymentAccountNumber        
+    else
+      begin
+        @my_bulk_merchant_addr[:email] = @merchant_email
+        merchant = developer.registerMerchantBulkAccount(
+          auth_obj, @my_bulk_merchant_addr)      
+      rescue => e
+        case e
+        when PBShipping::ApiError
+          if e.error_info.length < 1 
+            raise e
+          elsif !(e.error_info[0][:message].include?("Duplicate entry"))
+            raise e
+          end  
+          merchant = developer.getMerchantBulkAccount(auth_obj, @merchant_email)
+        else
+          raise e
+        end     
+      end
+      acct_num = developer.paymentAccount
+    end
+    return merchant, acct_num
+  end
+
+  def self.check_shipment_rate(auth_obj, developer)
+    rates = [ PBShipping::Rate.new(@my_rate_request_carrier_usps) ]
+    parcel = PBShipping::Parcel.new(@my_parcel)     
+    shipment = PBShipping::Shipment.new({
+      :fromAddress => PBShippingTestUtil::my_origin_addr, 
+      :toAddress => PBShippingTestUtil::my_dest_addr,
+      :parcel => parcel, 
+      :rates => rates
+    })
+    txid = PBShippingTestUtil::get_pb_tx_id()
+    xtra_hdrs = nil
+    if developer.bulkMode == true and developer.useShipperRate == true
+        xtra_hdrs = {"X-PB-Shipper-Rate-Plan" => "PP_SRP_NEWBLUE"}  
+    end  
+    rates = shipment.getRates(auth_obj, txid, true, xtra_hdrs) 
+    return rates[0].totalCarrierCharge   
+  end
+  
+  def self.create_single_shipment(auth_obj, developer, shipper_id)
+    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 => shipper_id }),
+      PBShipping::ShipmentOptions.new(
+        { :name => "ADD_TO_MANIFEST", :value => true })
+    ]      
+    shipment = PBShipping::Shipment.new({
+      :fromAddress => PBShippingTestUtil::my_origin_addr, 
+      :toAddress => PBShippingTestUtil::my_dest_addr,
+      :parcel => parcel, 
+      :rates => rates,
+      :documents => documents,
+      :shipmentOptions => shipmentOptions
+    })    
+    txid = PBShippingTestUtil::get_pb_tx_id()
+    xtra_hdrs = nil
+    if developer.bulkMode == true and developer.useShipperRate == true
+        xtra_hdrs = {"X-PB-Shipper-Rate-Plan" => "PP_SRP_NEWBLUE"}  
+    end    
+    shipment.createAndPurchase(auth_obj, txid, true, xtra_hdrs)       
+    return shipment, txid
+  end
+  
+  # verify the ledger balance is correct after shipment label purchase
+  def self.verify_ledger_balance_after_txn(shipment, start_balance, end_balance)
+    
+    balance_delta = BigDecimal(start_balance.balance - end_balance.balance, 3)
+    # if account has been replenished using auto-refill, skip this case
+    if balance_delta < 0
+      puts "    ending balance increases, probably due to auto reload, skip check"
+      return true
+    end
+    
+    txn_charge = BigDecimal(shipment.rates[0].totalCarrierCharge, 3)
+    
+    is_same = (txn_charge == balance_delta)
+    if is_same == false
+      delta = txn_charge - balance_delta
+      msg = "    verify balance failed: difference is " + delta.to_s
+      puts msg
+    end
+    
+    return is_same
+  end
+
+end