shippo 1.0.4 → 2.0.0

data/lib/shippo/api/category/purpose.rb

@@ -0,0 +1,13 @@
+require_relative 'base'
+module Shippo
+  module API
+    module Category
+      # Indicates whether a shipment can be used to purchase Labels or only to obtain quote Rates.
+      # Note that if at least one quote Address is passed in the original request,
+      # the Shipment will be eligible for quotes only.
+      class Purpose < Base
+        allowed_values :purchase, :quote
+      end
+    end
+  end
+end

data/lib/shippo/api/category/source.rb

@@ -0,0 +1,16 @@
+require_relative 'base'
+module Shippo
+  module API
+    module Category
+      #
+      # +Source+ category describes the origin of an address in the following way:
+      # * +:fully_entered+ addresses only contain user-given values and are eligible for purchasing a label.
+      # * +:partially_entered+ addresses lack some required information and only qualify for requesting rates.
+      # * +:validator+ addresses have been created by the address validation service.
+      #
+      class Source < Base
+        allowed_values :fully_entered, :partially_entered, :validator
+      end
+    end
+  end
+end

data/lib/shippo/api/category/state.rb

@@ -0,0 +1,13 @@
+require_relative 'base'
+module Shippo
+  module API
+    module Category
+      # "VALID" shipments contain all required values and can be used to get rates and purchase labels.
+      # "INCOMPLETE" shipments lack required values but can be used for getting rates.
+      # "INVALID" shipments can't be used for getting rates or labels.
+      class State < Base
+        allowed_values :valid, :invalid, :incomplete
+      end
+    end
+  end
+end

data/lib/shippo/api/category/status.rb

@@ -0,0 +1,17 @@
+require_relative 'base'
+module Shippo
+  module API
+    module Category
+      # +Status+ is a category class with the following possible values:
+      #
+      # * "Waiting" shipments have been successfully submitted but not yet been processed.
+      # * "Queued" shipments are currently being processed.
+      # * "Success" shipments have been processed successfully,
+      #    meaning that rate generation has concluded.
+      # * "Error" does not occur currently and is reserved for future use.
+      class Status < Base
+        allowed_values :waiting, :queued, :success, :error
+      end
+    end
+  end
+end

data/lib/shippo/api/extend/operation.rb

@@ -0,0 +1,21 @@
+module Shippo
+  module API
+    module Extend
+      module Operation
+        def self.included(klass)
+          klass.instance_eval do
+            class << self
+              def operations(*ops)
+                ops.each do |operation|
+                  module_name = "Shippo::API::Operations::#{operation.to_s.capitalize}"
+                  # noinspection RubyResolve
+                  self.extend(module_name.constantize)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shippo/api/extend/transformers.rb

@@ -0,0 +1,12 @@
+require_relative '../transformers/list.rb'
+module Shippo
+  module API
+    module Extend
+      module Transformers
+        def transformers
+          @transformers ||= [ Shippo::API::Transformers::List ].freeze
+        end
+      end
+    end
+  end
+end

data/lib/shippo/api/extend/url.rb

@@ -0,0 +1,26 @@
+module Shippo
+  module API
+    module Extend
+      module Url
+        def self.included(klass)
+          klass.instance_eval do
+            @url = nil
+            class << self
+              # It's a getter and a class-level setter
+              def url(value = nil)
+                return @url if @url
+                @url ||= value if value
+                @url ||= class_to_url
+              end
+
+              def class_to_url
+                words = self.short_name.underscore.split(/_/)
+                words.map { |w| "/#{w == words.last ? w.pluralize : w}" }.join
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shippo/api/operations.rb

@@ -0,0 +1,8 @@
+module Shippo
+  module API
+    module Operations
+    end
+  end
+end
+
+Shippo.dir('shippo/api/operations')

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

@@ -0,0 +1,33 @@
+require 'colored2'
+require 'awesome_print'
+module Shippo
+  module API
+    module Operations
+      module Create
+        # Creates an item in the database
+        # @param [Hash] params tacked onto the URL as URI parameters
+        def create(params={})
+          api_params = params.dup
+          Hashie::Extensions::StringifyKeys.stringify_keys!(api_params)
+
+          api_params.dup.each { |k, v| api_params[k] = v.id if v.is_a?(::Shippo::API::Resource) && v.id }
+
+          response = Shippo::API.post("#{url}/", api_params)
+          instance = self.from(response)
+
+          debug_log!(api_params, response, instance) if Shippo::API.debug?
+          instance
+        end
+
+        def debug_log!(api_params, response, instance)
+          puts "#{self.name}->create / request : \n".bold.green.underlined
+          ap(api_params)
+          puts "#{self.name}->create / response: \n".bold.yellow.underlined
+          ap(response)
+          puts "#{self.name}->create / from: \n".bold.blue.underlined
+          ap(instance)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+module Shippo
+  module API
+    module Operations
+      module List
+        # Return all items
+        # @param [Hash] params of additional URI parameters tacked onto the query URL
+        def all(params={})
+          response = Shippo::API.get("#{url}/", params)
+          self.from(response)
+        end
+
+        # Retrieve a concrete item by it's ID
+        # @param [Fixnum] id database ID of the item to be retrieved
+        # @param [Hash] params of additional URI parameters tacked onto the query URL
+        def get(id, params={})
+          response = Shippo::API.get("#{url}/#{CGI.escape(id)}/", params)
+          self.from(response)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+module Shippo
+  module API
+    module Operations
+      module Rates
+        def rates(currency = nil, params = {})
+          if !currency.nil?
+            response = Shippo::API.get("#{url}/rates/#{currency}/", params)
+          else
+            response = Shippo::API.get("#{url}/rates/", params)
+          end
+          Shippo::Rate.from(response[:results])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+module Shippo
+  module API
+    module Operations
+      module Update
+        def update(object_id, params={})
+          response = Shippo::API.put("#{url}/#{CGI.escape(object_id)}/", params)
+          self.from(response)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+module Shippo
+  module API
+    module Operations
+      module Validate
+        def validate(params={})
+          response = Shippo::API.get("#{url}/validate/", params)
+          Shippo::Address.from(response)
+        end
+      end
+    end
+  end
+end

data/lib/shippo/api/request.rb

@@ -0,0 +1,159 @@
+require 'rest_client'
+require 'socket'
+require 'json'
+require 'set'
+
+require 'shippo/exceptions'
+
+module Shippo
+  module API
+    #
+    # This class is the primary *internal* Interface to the Shippo API.
+    #
+    # Public consumers should use Model API, and perform actions on models
+    # rather than submit requests directly using this class.
+    #
+    # +Request+ instance is created with the intention to execute a single
+    # API call and once executed, it stores +response+ object.  Used
+    # requests can not be re-executed.
+    #
+    # == Example
+    #
+    #   @request = Shippo::API::Request.new(
+    #            method: :get,
+    #               uri: '/address,
+    #            params: { object_id: 1 },
+    #           headers: { 'Last-Modified' => '1213145' }
+    #   begin
+    #     @response = @request.execute
+    #     Shippo::Address.from(@response)
+    #   # =>
+    #
+    class Request
+      attr_accessor :username, :password
+      attr_accessor :method, :url, :params, :headers
+
+      # Result of the execute method is stored in #response and #parsed_response
+      attr_accessor :response, :parsed_response
+
+      # @param [symbol] method :get or any other method such as :put, :post, etc.
+      # @param [String] uri URI component appended to the base URL
+      # @param [Hash] params parameters to append to the URL
+      # @param [Hash] headers headers hash sent to the server
+      def initialize(method:, uri:, params: {}, headers: {})
+        self.method   = method
+        self.params   = params
+        self.headers  = headers
+        self.url      = api_url(uri)
+        self.response = nil
+      end
+
+      def execute
+        raise ArgumentError.new('Response is already defined, create another Request object.') if self.response
+        validate!
+        begin
+          self.response        = shippo_phone_home
+          self.parsed_response = JSON::parse(response.body, { symbolize_names: true })
+
+        rescue ::RestClient::Unauthorized => e
+          raise Shippo::Exceptions::AuthenticationError.new(e.message)
+
+        rescue ::JSON::JSONError, ::JSON::ParserError, ::RestClient::BadRequest
+          raise Shippo::Exceptions::APIServerError.new('Unable to read data received back from the server', self)
+
+        rescue ::RestClient::Exception => e
+          raise Shippo::Exceptions::ConnectionError.new(connection_error_message(url, e))
+
+        rescue StandardError => e
+          raise Shippo::Exceptions::ConnectionError.new(connection_error_message(url, e)) if e.message =~ /TCP|connection|getaddrinfo/
+
+          STDERR.puts "#{self.class.name}: Internal error occurred while connecting to #{url}: #{e.message}".bold.red
+          STDERR.puts 'Stack Trace'.bold.yellow.underlined
+          STDERR.puts e.backtrace.join("\n").yellow
+          raise Shippo::Exceptions::Error.new(e)
+        end
+        self.parsed_response
+      end
+
+      private
+
+      def shippo_phone_home
+        payload = {}
+        request_url = url
+        (method == :get) ? request_url = params_to_url(params, url) : payload = params.to_json
+        setup_headers!(headers)
+        opts = make_opts!(headers, method, payload, request_url)
+        make_request!(opts)
+      end
+
+      def make_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
+
+      def make_opts!(headers, method, payload, url)
+        { :headers      => headers,
+          :method       => method,
+          :payload      => payload,
+          :url          => url,
+          :open_timeout => 15,
+          :timeout      => 30,
+          :user         => username,
+          :password     => password,
+          :user_agent   => 'Shippo/v2.0 RubyBindings'
+        }
+      end
+
+      def setup_headers!(headers)
+        headers.merge!(
+          :accept        => :json,
+          :content_type  => :json,
+          :Authorization => "ShippoToken #{token}"
+        )
+      end
+
+      def base
+        ::Shippo::API.base
+      end
+
+      def token
+        ::Shippo::API.token
+      end
+
+      def connection_error_message(url, error)
+%Q[Could not connect to the Shippo API, via URL
+  #{url}.
+
+Please check your Internet connection, try again, if the problem
+persists please contact Shippo Customer Support.
+
+Error Description:
+  #{error.class.name} ⇨ #{error.message}].gsub(/^\s*/, '')
+      end
+
+      def api_url(uri_component = '')
+        base + uri_component
+      end
+
+      def params_to_url(params, url)
+        pairs = []
+        params.each { |k, v|
+          pairs.push "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}"
+        }
+        url += "?#{pairs.join('&')}" unless pairs.empty?
+        url
+      end
+
+      def validate!
+        raise Shippo::Exceptions::AuthenticationError.new(
+          'API credentials seems to be missing, perhaps you forgot to set Shippo::API.token?') \
+          unless token
+      end
+    end
+  end
+end

data/lib/shippo/api/resource.rb

@@ -0,0 +1,104 @@
+require 'forwardable'
+
+require 'hashie/mash'
+require 'active_support/inflector'
+
+require 'shippo/exceptions'
+
+require_relative 'api_object'
+require_relative 'category/status'
+require_relative 'transformers/list'
+require_relative 'extend/operation'
+require_relative 'extend/transformers'
+require_relative 'extend/url'
+
+module Shippo
+  module API
+    class Resource < Hashie::Mash
+      include Hashie::Extensions::StringifyKeys
+      include Enumerable
+      extend Forwardable
+
+      def self.object_properties
+        Shippo::API::ApiObject::PROPS
+      end
+
+      attr_accessor :object
+      def_delegators :@object, *object_properties
+
+      # Creates a possibly recursive chain (map of lists, etc) of Resource
+      # instances based on whether each value is a scalar, array or a hash.
+      def self.from(values)
+        # recursive on arrays
+        if values.is_a?(Array)
+          values.map { |list| from(list) }
+        elsif values.respond_to?(:keys) # a Hash or a Hash derivative
+          new(values)
+        else
+          values
+        end
+      end
+
+      def self.short_name(name = self.name)
+        name.split('::')[-1]
+      end
+
+      # Generate object_ accessors.
+      object_properties.each do |property|
+        method_name = ApiObject.field_name(property)
+        define_method method_name do
+          STDOUT.puts "#{method_name} style accessors are deprecated in favor of #resource.object.#{property}" if Shippo::API.warnings
+          self.object.send(property)
+        end
+      end
+
+      # allows resources to use default or a custom url
+      include Shippo::API::Extend::Url
+      # allows resources to set supported operations
+      include Shippo::API::Extend::Operation
+      # adds #transformers method that enumerates available transformers
+      # of the hashes into other types.
+      include Shippo::API::Extend::Transformers
+
+      # As a Hashie::Mash subclass, Resource can initialize from another hash
+      def initialize(*args)
+        if args.first.is_a?(Fixnum) or
+          (args.first.is_a?(String) && args.first =~ /^[0-9A-Fa-f]+$/)
+          self.id = args.first
+        elsif args.first.respond_to?(:keys)
+          h = Hashie::Mash.new(args.first)
+          self.deep_merge!(h)
+          self.object = ApiObject.create_object(self)
+          transformers.each do |transformer|
+            transformer.new(self).transform
+          end
+        else
+          super(*args)
+        end
+      end
+
+      def inspect
+        "#<#{self.class.short_name}:0x#{self.object_id.to_s(16)}#{id.nil? ? '' : "[id=#{id}]"}#{to_hash.inspect}->#{object.inspect}"
+      end
+
+      def to_s
+        self.class.short_name + self.to_hash.to_s + '->' + self.object.to_s
+      end
+
+      def url
+        raise Shippo::Exceptions::MissingDataError.new("#{self.class} has no object_id") unless id
+        "#{self.class.url}/#{CGI.escape(id)}"
+      end
+
+      def refresh
+        response = Shippo::API.get(url)
+        self.from(response)
+        self
+      end
+
+      def success?
+        self.object && self.object.status && self.object.status.eql?(Shippo::API::Category::Status::SUCCESS)
+      end
+    end
+  end
+end