pbshipping 1.0.0

data/lib/pbshipping/api_object.rb

@@ -0,0 +1,131 @@
+#
+# 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: api_object.rb
+# Description: base shipping api object class
+# 
+
+module PBShipping
+  class ApiObject
+    include Enumerable
+
+    def initialize(values=nil)
+      @values = {}
+      if values != nil
+        self.update(values)
+      end
+    end
+
+    def self.convert_to_api_object(values)
+      case values
+      when Array
+        values.map { |v| self.convert_to_api_object(v) }
+      when Hash
+        self.new(values)
+      else
+        values
+      end
+    end
+    
+    def update(values)
+      values.each do |k, v|
+        if v.is_a?(Array) || v.is_a?(Hash)
+          new_v = self.class.convert_to_api_object(v)
+        else
+          new_v = v
+        end
+        @values[k.to_sym] = new_v
+      end
+      instance_eval do
+        add_accessors(@values.keys)
+      end
+    end    
+
+    def [](k)
+      @values[k.to_sym]
+    end
+
+    def []=(k, v)
+      update({k => v})
+    end
+    
+    def keys
+      @values.keys
+    end
+
+    def values
+      @values.values
+    end
+
+    def to_s(*args)
+      JSON.pretty_generate @values
+    end
+
+    def to_json(*a)
+      JSON.dump(@values)
+    end
+
+    def as_json(*a)
+      @values.as_json(*a)
+    end
+
+    def to_hash
+      @values
+    end
+
+    def each(&blk)
+      @values.each(&blk)
+    end
+
+    def key?(k)
+      @values.key?(k)
+    end
+    
+    if RUBY_VERSION < '1.9.2'
+      def respond_to?(symbol)
+        @values.has_key?(symbol) || super
+      end
+    end
+
+    def inspect()
+      "#<#{self.class}:0x#{self.object_id.to_s(16)}}> json: " + self.to_s
+    end
+    
+    def create_accessor(k_name, k_index)
+      metaclass.instance_eval do
+        define_method(k_name) { @values[k_index] }
+        define_method(:"#{k_name}=") do |v|
+          @values[k_index] = v unless k_index == ''
+        end
+      end
+    end
+    
+    def add_accessors(keys)
+      keys.each do |k|
+        orig_k = k
+        while respond_to?(k) do
+          k = "_#{k}".to_sym
+        end
+        create_accessor(k, orig_k)
+      end
+    end
+    
+    def metaclass
+      class << self
+        self
+      end
+    end
+
+  end
+end

data/lib/pbshipping/api_resource.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: api_resource.rb
+# Description: base api resource class
+# 
+
+module PBShipping
+  class ApiResource < ApiObject
+  end
+end

data/lib/pbshipping/authentication.rb

@@ -0,0 +1,36 @@
+#
+# 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: authentication.rb
+# Description: handling authentication tasks for subsequent shipping api calls.
+# 
+
+module PBShipping
+  class AuthenticationToken
+    attr_accessor :api_key, :api_secret, :access_token, :auth_info
+    
+    def initialize(api_key, api_secret)
+      @api_key = api_key
+      @api_secret = api_secret
+      @access_token = nil
+      @auth_info = nil
+      refresh_token()
+    end
+    
+    def refresh_token()
+      @auth_info = PBShipping::authenticate_request(@api_key, @api_secret)
+      @access_token = @auth_info[:access_token]
+    end
+  end
+end

data/lib/pbshipping/carrier.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: carrier.rb
+# Description: carrier query such as supported countries
+# 
+
+module PBShipping
+  class Carrier < ShippingApiResource
+ 
+    #
+    # COUNTRIES LIST
+    # API: GET /countries
+    # API signature: get/countries
+    #
+    # Returns a list of supported destination countries to which the carrier 
+    # offers international shipping services. 
+    #
+    def getCountries(auth_obj, originCountryCode)
+      if self.key?(:name) == false
+        raise MissingResourceAttribute.new(:name)
+      end
+      params = {
+        "carrier" => self[:name], 
+        "originCountryCode" => originCountryCode
+        }
+      api_sig = "get/countries"
+      api_version = PBShipping::get_api_version(api_sig)
+      api_path = "/countries"
+      json_resp = PBShipping.api_request(auth_obj, :get, api_version, api_path, 
+                                         {}, params, {})
+      country_list = []
+      json_resp.each { |country| country_list << Country.new(country) }
+      return country_list
+    end
+    
+    def self.getCountriesForCarrier(auth_obj, carrier_name, originCountryCode)
+      return Carrier.new({:name => carrier_name}).getCountries(
+        auth_obj, originCountryCode)
+    end
+  end
+end

data/lib/pbshipping/country.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: country.rb
+# Description: base class for country objects.
+# 
+
+module PBShipping
+  class Country < ShippingApiResource
+  end
+end

data/lib/pbshipping/customs.rb

@@ -0,0 +1,26 @@
+#
+# 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: country.rb
+# Description: base class for custom objects.
+# 
+
+module PBShipping
+  class Customs < ShippingApiResource
+  end
+  class CustomsInfo < ShippingApiResource
+  end
+  class CustomsItem < ShippingApiResource
+  end    
+end

data/lib/pbshipping/developer.rb

@@ -0,0 +1,120 @@
+#
+# 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: developer.rb
+# Description: developer account query, merchant managements, and transaction 
+#              history query
+# 
+
+module PBShipping
+  class Developer < ShippingApiResource
+
+    # 
+    # CLIENT LIBRARY SPECIFIC
+    # API: GET /developers/{developerId}
+    # API signature: get/developers/...
+    # 
+    # Query for developer account attributes
+    #
+    def refresh(auth_obj)
+      if self.key?(:developerId) == false
+        raise MissingResourceAttribute.new(:developerId)
+      end
+      api_sig = "get/developers/.."
+      api_version = PBShipping::get_api_version(api_sig)
+      api_path = "/developers/" + self[:developerId]
+      json_resp = PBShipping::api_request(auth_obj, :get, api_version, api_path, {}, {}, {})
+      self.update(json_resp) 
+    end
+        
+    #
+    # MANAGING MERCHANTS
+    # API: GET /developers/{developerId}/merchants/emails/{emailId}/
+    # API signature: get/developers/.../merchants/emails/...
+    #
+    # Register your merchants or shippers, if you have signed up for the 
+    # individual account payment model.
+    #
+    # This method allows you to retrieve the merchant ID and related
+    # information based on the Email ID they used while registering, 
+    # so that you can request transactions on their behalf.  
+    #  
+    def registerMerchantIndividualAccount(auth_obj, emailid)
+      if self.key?(:developerId) == false
+        raise MissingResourceAttribute.new(:developerId)
+      end
+      api_sig = "get/developers/.../merchants/emails/..."
+      api_version = PBShipping::get_api_version(api_sig)
+      api_path = "/developers/" + self[:developerId]
+      api_path += "/merchants/emails/" + emailid + "/"
+      Merchant.new(PBShipping::api_request(
+        auth_obj, :get, api_version, api_path, {}, {}, {}))
+    end
+
+    #
+    # CLIENT LIBRARY SPECIFIC
+    # API: GET /developers/{developerId}/merchants/emails/{emailId}/
+    # API signature: get/developers/.../merchants/emails/...
+    # 
+    # Query for merchant details using merchant's email address if developer
+    # is operating in bulk mode
+    #
+    def getMerchantBulkAccount(auth_obj, emailid)
+      # use the same underlying REST call
+      return self.registerMerchantIndividualAccount(auth_obj, emailid)
+    end
+        
+    #
+    # MANAGING MERCHANTS
+    # API: POST /developers/{developerId}/merchants/registration
+    # API signature: post/developers/.../merchants/registration
+    #   
+    # Register your merchants or shippers, if you have signed up for the 
+    # bulk account payment model.
+    # 
+    # This method allows you to retrieve the merchant ID and related
+    # information, so that you can request transactions on their behalf. 
+    #    
+    def registerMerchantBulkAccount(auth_obj, address)
+      if self.key?(:developerId) == false
+        raise MissingResourceAttribute.new(:developerId)
+      end
+      api_sig = "post/developers/.../merchants/registration"
+      api_version = PBShipping::get_api_version(api_sig)
+      api_path = "/developers/" + self[:developerId]
+      api_path += "/merchants/registration"
+      Merchant.new(PBShipping::api_request(
+        auth_obj, :post, api_version, api_path, {}, {}, address))
+    end
+ 
+    #
+    # MANAGING MERCHANTS
+    # API: GET /ledger/developers/{developerId}/transactions/reports
+    # API signature: get/ledger/developers/.../transactions/reports
+    #
+    # Retrieve all transactions based on the given input parameters   
+    #      
+    def getTransactionReport(auth_obj, params)
+      if self.key?(:developerId) == false   
+        raise MissingResourceAttribute.new(:developerId)
+      end  
+      api_sig = "get/ledger/developers/.../transactions/reports"
+      api_version = PBShipping::get_api_version(api_sig)
+      api_path = "/ledger/developers/" + self[:developerId]
+      api_path += "/transactions/reports"
+      ApiObject.new(PBShipping::api_request(
+        auth_obj, :get, api_version, api_path, {}, params, {}))
+    end
+  end
+end

data/lib/pbshipping/error.rb

@@ -0,0 +1,73 @@
+#
+# 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: error.rb
+# Description: class encapsulating shipping api exceptions/errors.
+# 
+
+module PBShipping
+  class ApiError < StandardError
+    attr_reader :message, :http_code, :http_body, :error_info
+    def initialize(message, http_code=nil, http_body=nil)
+      @message = message
+      @http_code = http_code
+      @http_body = http_body
+      @error_info = []
+      if http_body != nil 
+        begin 
+          json_error = PBShipping::json_parse(http_body)
+        rescue => e
+        end
+        if json_error.is_a?(Array)
+          for next_err in json_error
+            if next_err.key?(:key) == true 
+              @error_info << {
+                :errorCode => next_err[:key], 
+                :message => next_err[:message]
+              }
+            elsif next_err.key?(:errorCode) == true
+              @error_info << {
+                :errorCode => next_err[:errorCode], 
+                :message => next_err[:message]
+              }
+            end
+          end
+        elsif json_error.is_a?(Hash) && json_error.key?(:errors)
+          for next_err in json_error[:errors]
+            @error_info << {
+              :errorCode => next_err[:errorCode],
+              :message => next_err[:errorDescription]
+            }
+          end
+        end
+      end
+    end
+
+    def to_s
+      if http_body != nil
+        msg = @message + " " + http_body.to_s
+      else
+        msg = @message
+      end
+      return msg
+    end
+  end
+  class AuthenticationError < ApiError
+  end
+  class MissingResourceAttribute < ApiError
+    def initialize(missing_attr)
+      super("Attribute " + missing_attr.to_s + " is missing")
+    end
+  end
+end