pbshipping 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: febf1d66b2a57a7ac60318cf1cdd61481592cd65
+  data.tar.gz: 1cfe22e324612b25cd6458affe073fea73db418d
+SHA512:
+  metadata.gz: 7d28b3263a39ad532070a258fb546baa8a87ffca109d07d236fded03baf915a56ae681d701a29fcd6b4b61a8f24eddeee528db8d7d01294a7a1088861bd102c0
+  data.tar.gz: ea1f7d18cf0235a0b57d2dce0032898193975394a455a31e24b6e3f9d37f1388ca4fa2c43445f98d5c9c403482cb8594f0b727ae9167f8b6c2b67fd8f6531efa

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2016 Pitney Bowes Inc.
+
+The Shipping API for Client Library (Ruby) is licensed under the following license:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this 
+software and associated documentation files (the "Software"), to deal in the Software 
+without restriction, including without limitation the rights to use, copy, modify, 
+merge, publish, distribute, sublicense, and/or sell copies of the Software, and to 
+permit persons to whom the Software is furnished to do so, subject to the following 
+conditions:
+
+The above copyright notice and this permission notice shall be included in all copies 
+or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE 
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR 
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
+DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,185 @@
+# Pitney Bowes Shipping Client Library for Ruby
+[![gem version](https://badge.fury.io/rb/pbshipping.svg)](https://badge.fury.io/rb/pbshipping)
+
+The Pitney Bowes Shipping Services APIs provide easy access to United States 
+Postage Service shipping and tracking services that can be easily integrated 
+into any web application such as online shopping carts, e-commerce sites or 
+multi-carrier applications. 
+
+This package provides a wrapper layer allowing easy access to the Pitney Bowes 
+shipping REST APIs in the Ruby programming language.  
+
+You would need a Pitney Bowers developer account for testing and using the API
+and the client library.
+
+For more informaton please visit the 
+[Pitney Bowes developer portal](http://developer.pitneybowes.com).
+
+## Installation
+ 
+You can clone or download the source from Github repository (https://github.com/pitneybowes/pitneybowes-shipping-api-ruby) or
+install as [Ruby gem)](https://rubygems.org/).
+
+## Dependencies
+
+You would need to install Ruby rest-client (https://rubygems.org/gems/rest-client/), version 1.8 or later.
+
+## Registration
+
+Make sure you have signed up a developer account on the 
+[Pitney Bowes developer portal](http://developer.pitneybowes.com).
+
+Once you have successfully registered for a developer account, sign in and
+you can access your API test key (`API key` and `API secret`) from the *Dashboard*
+page. 
+
+You can also access your `Developer ID` (e.g.: 12345678) from the *My Account* 
+page.
+
+By default, your developer account is configured to work with individual 
+merchant account payment model. In this caes, each merchant signs up for 
+a Pitney Bowes shipment account directly and their funds are directly 
+managed by Pitney Bowes. 
+
+For testing purpose, you can create a merchant account 
+at https://developer.pbshippingmerchant.pitneybowes.com/home?developerID={DeveloperID}.
+Make sure you replace the placeholder in the URL with your own developer ID.
+
+You will use the `email address` for registering the merchant account for
+identifying the corresponding mercchant in the shipping API call. 
+
+## Understanding Configuration
+
+The client library provides a configuration object (*lib/pbshipping.rb*) for 
+managing configuraton for environment using the Shipping APIs. The values 
+for each parameter can be readily accessed and modified programmatically:
+
+```
+module PBShipping
+
+  @configuration = {
+    :sandbox => "https://api-sandbox.pitneybowes.com",
+    :production => "https://api.pitneybowes.com",
+    :is_production => false,
+    :default_api_version => "/v1",
+    :overwrite_api_version => {
+      "post/developers/.../merchants/registration" => "/v2",
+      "get/ledger/developers/.../transactions/reports" => "/v2"
+    }
+  }
+  . . . . . 
+```
+* *sandbox* and *production* refer to the URL pointing at the testing (sandbox)
+and production server supporting the endpoints;
+* *is_production* controls if the application should run in sandbox or 
+production mode;
+* *default_api_version* defines the default API version to be used in general 
+except for cases where explict overrides are specified;
+* *override_api_version* is a set (Ruby Hash) of API version 
+overrides for specific API calls; each entry defines the particular version 
+to be used for the corresponding API.
+
+#### Choosing API version
+
+You may need to use different version number for diferent Shipping APIs. 
+This can be accomplished by customizing the *defaul_api_version* and 
+*override_api_version* entries in the *Configuration.params* structure. 
+
+To specify the version number of a particular call type:
+* Identify the *signature* for the API call; the signature mimics the relative
+path of the API and can be found in the comment headers in the resource files
+(*account.rb, address.rb, carrier.rb, developer.rb, manifest.rb, shipmente.rb, tracking.rb*).
+* Add an entry to *override_api_version* in the format 
+*<api signature>: <verson string>* 
+
+
+## Running the Tutorials
+
+A tutorial *tutorial.rb* is provided to demonstrate how to use the different class and
+methods available through the client library to consume the shipping services.
+
+*Note: if you clone or download the source from Github and run the tutorial example
+directly, make sure you include the lib directory/folder in your Ruby library path (RUBYLIB).*
+
+```
+ruby tutorial.rb
+```
+
+You would need to set your authentication (key and secret), 
+developer (ID), and merchant (email) credentials either through environment 
+variables or command line arguments.
+
+### Setting through Environment Variables
+
+The following four varaibles should be set:
+* PBSHIPPING_KEY: your assigned API key
+* PBSHIPPING_SECRET: your assigned API secret
+* PBSHIPPING_DEVID: your Developer ID
+* PBSHIPPING_MERCHANT: email address for the regsitered merchant account
+
+```
+export PBSHIPPING_KEY=<api key>
+export PBSHIPPING_SECRET=<api secret>
+export PBSHIPPING_DEVID=<developer id>
+export PBSHIPPING_MERCHANT=<merchant email address>
+```
+
+### Setting through Command Line Arguments
+
+Use the command line long options *--key*, *--secret*, *--devid*, and *--merchant*:
+
+```
+ruby tutorial_client_library.rb --key=<your key> --secret=<your secret> 
+                                --devid==<developer id> 
+                                --merchant=<merchant email>
+```
+
+## Running Test 
+
+The test suite can be found under the *test* directory and can be run as follows:
+
+```
+ruby ts_all_tests.rb 
+```
+
+Similar to the tutorial, you have to set the authentication, developer, and 
+merchant settings through environment variables to run the test.
+
+## Documentation
+
+The Pitney Bowes Shipping Services API (REST) documentation can be found at the 
+[Pitney Bowes developer portal](http://developer.pitneybowes.com).
+
+Developers are also encouraged to use the tutorial example and source code 
+comment blocks for information on the wrapper layer interface and mapping to 
+the underlying REST shipping APIs. 
+
+## Attribution Notice
+
+This product contains Rest-client Ruby, version number 1.8, which is licensed 
+under the MIT license. The license can be downloaded from https://opensource.org/licenses/MIT.
+
+The source code for this software is available from http://www.rubydoc.info/gems/rest-client/1.8.0.
+
+## License
+
+Copyright 2016 Pitney Bowes Inc.
+
+The Shipping API for Client Library (Ruby) is licensed under the following license:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this 
+software and associated documentation files (the "Software"), to deal in the Software 
+without restriction, including without limitation the rights to use, copy, modify, 
+merge, publish, distribute, sublicense, and/or sell copies of the Software, and to 
+permit persons to whom the Software is furnished to do so, subject to the following 
+conditions:
+
+The above copyright notice and this permission notice shall be included in all copies 
+or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE 
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR 
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
+DEALINGS IN THE SOFTWARE.

data/lib/pbshipping.rb

@@ -0,0 +1,173 @@
+#
+# 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: pbshipping.rb
+# Description: top level shipping api client library source including 
+#              configuration facilitiies
+# 
+
+require 'rest-client'
+require 'json'
+require 'base64'
+require 'bigdecimal'
+
+require_relative 'pbshipping/error.rb'
+require_relative 'pbshipping/api_object.rb'
+require_relative 'pbshipping/api_resource.rb'
+require_relative 'pbshipping/shipping_api_resource.rb'
+require_relative 'pbshipping/account.rb'
+require_relative 'pbshipping/address.rb'
+require_relative 'pbshipping/authentication.rb'
+require_relative 'pbshipping/carrier.rb'
+require_relative 'pbshipping/country.rb'
+require_relative 'pbshipping/customs.rb'
+require_relative 'pbshipping/developer.rb'
+require_relative 'pbshipping/manifest.rb'
+require_relative 'pbshipping/merchant.rb'
+require_relative 'pbshipping/parcel.rb'
+require_relative 'pbshipping/rate.rb'
+require_relative 'pbshipping/scandetails.rb'
+require_relative 'pbshipping/shipment.rb'
+require_relative 'pbshipping/tracking.rb'
+require_relative 'pbshipping/transactiondetails.rb'
+
+module PBShipping
+
+  @configuration = {
+    :sandbox => "https://api-sandbox.pitneybowes.com",
+    :production => "https://api.pitneybowes.com",
+    :is_production => false,
+    :default_api_version => "/v1",
+    :override_api_version => {
+      "post/developers/.../merchants/registration" => "/v2",
+      "get/ledger/developers/.../transactions/reports" => "/v2"
+    }
+  }
+  @api_group_shipping = "/shippingservices"
+  @txid_attrname = "X-PB-TransactionId"    
+
+  class << self
+    attr_accessor :configuration, :api_group_shipping, :txid_attrname
+  end
+
+  def self.get_api_version(api_sig)
+    if @configuration[:override_api_version].key?(api_sig) == true
+      api_version = @configuration[:override_api_version][api_sig]
+    else 
+      api_version = @configuration[:default_api_version]
+    end
+    return api_version  
+  end
+  
+  def self.api_url(api_version, api_path)
+    if @configuration[:is_production] == true
+      api_server = @configuration[:production]
+    else
+      api_server = @configuration[:sandbox] 
+    end
+    api_server + @api_group_shipping + api_version + api_path
+  end
+
+  def self.authenticate_request(api_key, api_secret)
+    if @configuration[:is_production] == true
+      api_server = @configuration[:production]
+    else
+      api_server = @configuration[:sandbox] 
+    end
+    url = api_server + "/oauth/token"
+   
+    headers = {
+      :content_type => 'application/x-www-form-urlencoded',
+      :Authorization => 'Basic ' + Base64.strict_encode64(api_key + ":" + api_secret)
+    }
+    payload = {
+      :grant_type => 'client_credentials'
+    }
+    opts = {
+      :method => 'post',
+      :payload => payload,
+      :headers => headers,
+      :url => url,
+      :open_timeout => 15,
+      :timeout => 30
+    }
+    
+    begin
+      res = make_http_request(opts)
+      json_parse(res)
+    rescue => e
+      case e
+      when RestClient::Exception
+        raise AuthenticationError.new(e.to_s, e.http_code, e.http_body) 
+      else
+        raise AuthenticationError.new(e.to_s)
+      end           
+    end  
+  end
+  
+  def self.api_request(auth_obj, method, api_version, api_path, headers = {}, params = {}, payload = {})
+    if auth_obj == nil || auth_obj.access_token == nil
+      raise AuthenticationError.new("Invalid or missing authentication credentials")
+    end
+    begin
+      url = api_url(api_version, api_path)
+      headers.merge!(
+        :accept => :json,
+        :content_type => :json,
+        :Authorization => "Bearer " + auth_obj.access_token
+      )
+      case method
+      when :get    
+        payload = {}        
+        pairs = []
+        params.each { |k, v|
+          pairs.push "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}"
+        }
+        url += "?#{pairs.join('&')}" unless pairs.empty?
+      end
+      opts = { 
+        :headers => headers,
+        :method => method,
+        :payload => payload.to_json,
+        :url => url,
+        :open_timeout => 15,
+        :timeout => 30,
+        :user_agent => "pbshipping/v1 RubyBindings"
+      }
+      res = make_http_request(opts)
+      json_parse(res)      
+    rescue => e
+      case e
+      when RestClient::Exception
+        raise ApiError.new(e.to_s, e.http_code, e.http_body) 
+      else
+        raise ApiError.new(e.to_s)
+      end 
+    end
+  end
+  
+  def self.json_parse(response)
+    JSON::parse(response.body, { :symbolize_names => true })
+  end
+end
+
+def make_http_request(opts)
+  RestClient::Request.execute(opts){ |response, request, result, &block|
+    if [301, 302, 307].include? response.code
+      response.follow_redirection(request, result, &block)
+    else
+      response.return!(request, result, &block)
+    end
+  }
+end

data/lib/pbshipping/account.rb

@@ -0,0 +1,45 @@
+#
+# 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: account.rb
+# Description: account management functions
+# 
+
+module PBShipping
+  class Account < ShippingApiResource
+    
+    #
+    # MANAGING MERCHANTS
+    # API: GET /ledger/accounts/{accountNumber}/balance
+    # API signature: get/ledger/accounts/.../balance
+    #
+    # Retrieve the account balance of a merchant account.   
+    #    
+    def getBalance(auth_obj)
+      if self.key?(:accountNumber) == false
+        raise MissingResourceAttribute.new(:accountNumber)
+      end
+      api_sig = "get/ledger/accounts/.../balance"
+      api_version = PBShipping::get_api_version(api_sig)
+      api_path = "/ledger/accounts/" + self[:accountNumber] + "/balance"
+      json_resp = PBShipping.api_request(auth_obj, :get, api_version, api_path, 
+                                         {}, {}, {})
+      return ApiObject.new(json_resp)
+    end
+    
+    def self.getBalanceByAccountNumber(auth_obj, accountNumber)
+      return Account.new({:accountNumber => accountNumber}).getBalance(auth_obj)
+    end
+  end
+end

data/lib/pbshipping/address.rb

@@ -0,0 +1,55 @@
+#
+# 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: address.rb
+# Description: address verification functions
+# 
+
+module PBShipping
+  class Address < ShippingApiResource    
+
+    #
+    # ADDRESS VALIDATION
+    # API: POST /addresses/verify
+    # API signature: post/addresses/verify
+    #
+    # Verify and cleanse any postal address within the United States. 
+    # This will ensure that packages are rated accurately and the 
+    # shipments arrive at their final destination on time.
+    #
+    # By default, the returned result would overwrite the current state 
+    # of the object. To avoid overwriting, set the input argument 
+    # overwrite to False and a copy of the result would be generated and
+    # returned instead      
+    #
+    def verify(auth_obj, minimalAddressValidation=nil, overwrite=true)
+      if minimalAddressValidation == nil
+        hdrs = {"minimalAddressValidation" => false}
+      else
+        hdrs = {"minimalAddressValidation" => minimalAddressValidation}
+      end
+      api_sig = "post/address/verify"
+      api_version = PBShipping::get_api_version(api_sig)
+      api_path = "/addresses/verify"
+      json_resp = PBShipping::api_request(
+        auth_obj, :post, api_version, api_path, hdrs, {}, self)
+      if overwrite == true 
+        self.update(json_resp)
+        self
+      else  
+        Address.new(json_resp)
+      end  
+    end
+  end
+end