shippo 1.0.4 → 2.0.0

data/lib/shippo.rb

@@ -1,104 +1,30 @@
-require 'rest_client'
-require 'json'
-require 'set'
-
-require_relative 'shippo/error.rb'
-require_relative 'shippo/container_object.rb'
-require_relative 'shippo/api_object.rb'
-require_relative 'shippo/resource.rb'
-
-# api operations
-require_relative 'shippo/create.rb'
-require_relative 'shippo/update.rb'
-require_relative 'shippo/list.rb'
-
-
-# api objects
-require_relative 'shippo/address.rb'
-require_relative 'shippo/carrieraccount.rb'
-require_relative 'shippo/customs_item.rb'
-require_relative 'shippo/customs_declaration.rb'
-require_relative 'shippo/manifest.rb'
-require_relative 'shippo/parcel.rb'
-require_relative 'shippo/rate.rb'
-require_relative 'shippo/refund.rb'
-require_relative 'shippo/shipment.rb'
-require_relative 'shippo/transaction.rb'
+#
+# +Shippo+ is the ruby module enclosing all and any ruby-based
+# functionality developed by Shippo, Inc.
+#
+# This gem providers wrappers for Shippo API in ruby. You are
+# not required to use any particular library to access Shippo
+# API, but it is our hope that this gem helps you bootstrap your
+# Shippo integration.
+#
+
+require 'require_dir'
 
 module Shippo
-  @api_base = 'https://api.goshippo.com/v1'
-  @api_version = 1.0
-  @api_token = ''
-
-  class << self
-    attr_accessor :api_base, :api_version, :api_token
-  end
+  extend ::RequireDir
+  init_from_source __FILE__
+end
 
-  def self.api_url(url='')
-    @api_base + url
-  end
+require 'shippo/api'
 
-  def self.request(method, url, params = {}, headers = {})
-    if @api_token.empty?
-      raise AuthError.new("API credentials missing! Make sure to set Shippo.api_token")
-    end
-    begin
-      payload = {}
-      url = api_url(url)
-      headers.merge!(
-        :accept => :json,
-        :content_type => :json,
-        :Authorization => "ShippoToken #{@api_token}"
-      )
-      case method
-      when :get
-        pairs = []
-        params.each { |k, v|
-          pairs.push "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}"
-        }
-        url += "?#{pairs.join('&')}" unless pairs.empty?
-      else
-        payload = params.to_json
-      end
-      opts = { :headers => headers,
-        :method => method,
-        :payload => payload,
-        :url => url,
-        :open_timeout => 15,
-        :timeout => 30,
-        :user => @api_user,
-        :password => @api_pass,
-        :user_agent => "Shippo/v1 RubyBindings"
-      }
-      res = make_request(opts)
-    rescue => e
-      case e
-      when RestClient::ServerBrokeConnection, RestClient::RequestTimeout
-        msg = "Could not connect to the Shippo API at #{@api_base}. " +
-        "Please proceed to check your connection, try again and " +
-        "contact Shippo support should the issue persist."
-        raise ConnectionError.new msg + "\n\n(e.message)"
-      when SocketError
-        msg = "Unexpected error connecting to the Shippo API at #{@api_base}."
-      when RestClient::ExceptionWithResponse
-        msg = "error: #{e} #{e.http_body}"
-      else
-        msg = "error: #{e}"
-      end
-      raise APIError.new msg
-    end
-    parse(res)
+# Backwards compatibility
+module Shippo
+  def self.api_key(value)
+    ::Shippo::API.token = value
   end
-  def self.parse(response)
-    JSON::parse(response.body, { :symbolize_names => true })
+  class << self
+    alias_method :api_key=, :api_key
+    alias_method :api_token=, :api_key
   end
 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
+

data/lib/shippo/api.rb

@@ -0,0 +1,52 @@
+require 'rest_client'
+require 'json'
+require 'set'
+
+require_relative '../shippo' unless defined?(Shippo) && Shippo.respond_to?(:dir_r)
+
+require 'shippo/exceptions'
+require 'shippo/api/category'
+require 'shippo/api/request'
+require 'shippo/api/resource'
+
+module Shippo
+  module API
+    @base     = 'https://api.goshippo.com/v1'
+    @version  = 1.0
+    @token    = ''
+    @debug    = Integer(ENV['SHIPPO_DEBUG'] || 0) > 0 ? true : false
+    @warnings = true
+
+    class << self
+      attr_accessor :base, :version, :token, :debug, :warnings
+      # @param [Symbol] method One of :get, :put, :post
+      # @param [String] uri the URL component after the first slash but before params
+      # @param [Hash] params hash of optional parameters to add to the URL
+      # @param [Hash] headers optionally added headers
+      def request(method, uri, params = {}, headers = {})
+        ::Shippo::API::Request.new(method:  method,
+                                   uri:     uri,
+                                   params:  params,
+                                   headers: headers).execute
+      end
+
+      %i[get put post].each do |method|
+        define_method method do |*args|
+          uri, params, headers = *args
+          request(method, uri, params || {}, headers || {})
+        end
+      end
+
+      def debug?
+        Shippo::API.debug
+      end
+    end
+  end
+end
+
+Shippo.dir('shippo/api')
+Shippo.dir('shippo/api/transformers')
+Shippo.dir('shippo/api/extend')
+Shippo.dir('shippo/model')
+
+

data/lib/shippo/api/api_object.rb

@@ -0,0 +1,133 @@
+require 'hashie/dash'
+require 'hashie/extensions/stringify_keys'
+require 'hashie/extensions/symbolize_keys'
+require 'hashie/extensions/dash/property_translation'
+require 'active_support/inflector'
+
+module Shippo
+  module API
+    # +ApiObject+ is a class that contains only a set of specific fields
+    # that can be used in both requests and responses from Shippo API.
+    # Upon return with each response, +ApiObject+ instance is automatically
+    # created and populated with fields that begin with a prefix `object_`.
+    # The prefix is deleted, and the fields are made available through the
+    # non-prefixed accessors.
+    #
+    # This class uses +Hashie::Dash+ under the hood, in order to provide convenient
+    # transformations, support required/optional attributes, etc.
+    #
+    #
+    # == Example
+    #
+    # ```ruby
+    # response = {
+    #       "object_state" => "VALID",
+    #     "object_purpose" => "PURCHASE",
+    #      "object_source" => "FULLY_ENTERED",
+    #     "object_created" => "2014-07-16T23:20:31.089Z",
+    #     "object_updated" => "2014-07-16T23:20:31.089Z",
+    #          "object_id" => "747207de2ba64443b645d08388d0309c",
+    #       "object_owner" => "shippotle@goshippo.com",
+    #               "name" => "Shawn Ippotle",
+    #            "company" => "Shippo",
+    #            "street1" => "215 Clayton St.",
+    #            "street2" => "",
+    #               "city" => "San Francisco",
+    #              "state" => "CA",
+    #                "zip" => "94117",
+    #            "country" => "US",
+    #              "phone" => "+1 555 341 9393",
+    #              "email" => "shippotle@goshippo.com"
+    # }
+    #
+    # require 'shippo'
+    # address = Shippo::Address.from(response)
+    # address.name
+    # # ⤷ Shawn Ippotle
+    # require 'ap'
+    # ap address.object
+    # # ⤷
+    # {
+    #       :state => #<Shippo::API::Category::State:0x007fd374b4d0d0 @name=:state, @value=:valid>,
+    #     :purpose => #<Shippo::API::Category::Purpose:0x007fd373df2070 @name=:purpose, @value=:purchase>,
+    #      :source => #<Shippo::API::Category::Source:0x007fd374b4fbf0 @name=:source, @value=:fully_entered>,
+    #     :created => 2014-07-16 23:20:31 UTC,
+    #     :updated => 2014-07-16 23:20:31 UTC,
+    #          :id => "747207de2ba64443b645d08388d0309c",
+    #       :owner => "shippotle@goshippo.com"
+    # }
+    # ```
+    class ApiObject < Hashie::Dash
+      include Hashie::Extensions::Dash::PropertyTranslation
+
+      PREFIX           = { id: 'resource_', default: 'object_' }.freeze
+
+      class << self
+        def field_name(property)
+          "#{PREFIX[property.to_sym] || PREFIX[:default]}#{property}".to_sym
+        end
+
+        def matches_prefix?(value)
+          %r[^(#{PREFIX.values.join('|')})].match(value.to_s)
+        end
+
+        def mk_opts(property)
+          { with: ->(value) { value }, from: "#{field_name(property)}".to_sym, required: false }
+        end
+      end
+
+      # list of allowed properties, of a given type.
+      PROPS_ID         = %i(id).freeze
+      PROPS_CATEG      = %i(state purpose source status).freeze
+      PROPS_EMAIL      = %i(owner).freeze
+      PROPS_TIMED      = %i(created updated).freeze
+
+      PROPS            = (PROPS_ID + PROPS_EMAIL + PROPS_TIMED + PROPS_CATEG ).flatten.freeze
+      PROPS_AS_IS      = (PROPS_EMAIL + PROPS_ID).freeze
+
+      def self.setup_property(prop, custom = {})
+        property prop, self.mk_opts(prop).merge(custom)
+      end
+
+      PROPS_AS_IS.each { |prop| setup_property(prop) }
+      PROPS_TIMED.each { |prop| setup_property(prop, with: ->(value) { Time.parse(value) } ) }
+      PROPS_EMAIL.each { |prop| setup_property(prop, with: ->(value) {
+          value && value.strip!
+          value = "#{value}@gmail.com" if value and value !~ %r[.*@.*\..*]
+          value
+        })
+      }
+      PROPS_CATEG.each { |prop| setup_property(prop, with: ->(value) {
+        Shippo::API::Category.for(prop, value)
+        })
+      }
+
+      def self.create_object(h)
+        object_keys = h.keys.select { |k| matches_prefix?(k) }
+        h_object    = {}
+        object_keys.each { |k| h_object[k.to_s] = h[k] }
+        instance = self.new(h_object)
+        object_keys.each { |k| h.delete(k) if h.key(k) }
+        instance
+      end
+
+      def initialize(*args)
+        opts = args.first
+        if opts && opts.respond_to?(:keys)
+          Hashie::Extensions::SymbolizeKeys.symbolize_keys!(opts)
+          if opts[:object_id]
+            opts[(PREFIX[:id] + 'id').to_sym] = opts[:object_id]
+            opts.delete(:object_id)
+          end
+          super(opts)
+        else
+          super(args)
+        end
+      end
+
+      def to_s
+        Shippo::API::Resource.short_name(self.class.name) + self.to_hash.to_s
+      end
+    end
+  end
+end

data/lib/shippo/api/category.rb

@@ -0,0 +1,49 @@
+require 'hashie/dash'
+require 'active_support/inflector'
+require 'shippo/exceptions'
+module Shippo
+  module API
+    # For enumerations with discrete possible set of values, +Category+ class
+    # offers it's subclasses and users tremendous benefits.
+    #
+    # Categories should be always created via the Facåde
+    # +Shippo::API::Category.for(name, value)+. Although it is possible to
+    # directly instantiate subclasses, it is not recommended for performance reasons.
+    #
+    # == Example
+    #
+    # ```ruby
+    # require 'shippo/api'
+    # class My::Big::Module::Size < ::Shippo::API::Category::Base
+    #   allowed_values :small, :medium, :large, :xlarge, :xxlarge
+    # end
+    # # ⤷ [:small, :medium, :large, :xlarge, :xxlarge]
+    #
+    # my_size = Shippo::API::Category.for('size', 'xlarge')
+    # # ⤷ XLARGE
+    # my_size.class.name
+    # # ⤷ My::Big::Module::Size
+    # ```
+
+    module Category
+      @categories = {}
+      class << self
+        attr_accessor :categories
+      end
+
+      class DuplicateValueError < ::Shippo::Exceptions::APIError;
+      end
+
+      def self.key(value)
+        value.to_s.downcase.to_sym
+      end
+
+      def self.for(name, value)
+        cat = self.categories[name.to_s.downcase.to_sym]
+        cat ? cat[value.to_s.downcase.to_sym] : nil
+      end
+    end
+  end
+end
+
+Shippo.dir('shippo/api/category')

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

@@ -0,0 +1,144 @@
+module Shippo
+  module API
+    module Category
+      # +Base+ is a convenience abstract class that provides the following functionality
+      # to it's subclasses, which are meant to be enumerations with a fixed number of possible
+      # values.
+      #
+      # Base populates a global hash +Shippo::API::Category.categories+ which is keyed by the
+      # lower cased and symbolized category name (eg, :status or :purpose), each value is another
+      # hash consisting of keys (values of each category, eg :success, :error) and value being the
+      # constant created for such a value.
+      #
+      # __WARNING__: You are not supposed to instantiate these classes, to be honest. The
+      # "correct" way is via the Facåde +Shippo::API::Category.for(name, value)+.
+      #
+      # == Example
+      #
+      # ```ruby
+      # require 'shippo/api'
+      # class Size < ::Shippo::API::Category::Base
+      #   allowed_values :small, :medium, :large, :xlarge, :xxlarge
+      # end
+      # # ⤷ [:small, :medium, :large, :xlarge, :xxlarge]
+      #
+      # my_size = Shippo::API::Category.for('size', 'xlarge')
+      # # ⤷ size:xlarge
+      #
+      # my_size.xlarge?
+      # # ⤷ true
+      # my_size.medium?
+      # # ⤷ false
+      # my_size.name
+      # # ⤷ size
+      # my_size.value
+      # # ⤷ xlarge
+      #
+      # medium_1 = Size.new('medium')
+      #  ⤷ size:medium
+      # medium_2 = Size.new('medium')
+      #  ⤷ size:medium
+      # medium_3 = Shippo::API::Category.for(:size, :medium)
+      #  ⤷ size:medium
+      #
+      # # But keep in mind these instances are all different objects,
+      # # which are +eql?()+ to each other, but not identical.
+      # medium_1.object_id
+      # # ⤷ 70282669124280
+      # medium_2.object_id
+      # # ⤷ 70282669580500
+      # medium_3.object_id
+      # # ⤷ 70282681963740
+      # medium_1.eql?(medium_2)
+      # # ⤷ true
+      # medium_2.eql?(medium_3)
+      # # ⤷ true
+      # ```
+      #
+      class Base
+
+        @categories = Shippo::API::Category.categories
+        class << self
+          attr_accessor :categories
+        end
+
+        def self.inherited(klazz)
+          klazz.instance_eval do
+            @allowed_values = Set.new
+            class << self
+              def categories
+                ::Shippo::API::Category::Base.categories
+              end
+
+              def value_transformer(values)
+                values.map(&:downcase).map(&:to_sym)
+              end
+
+              def allowed_values(*values)
+                return @allowed_values if values.nil? || values.empty? || !@allowed_values.empty?
+
+                @allowed_values = self.value_transformer(values)
+                @allowed_values.each do |allowed_value|
+                  category_value = Category.key(allowed_value)
+                  category_const = category_value.to_s.upcase
+
+                  raise ::Shippo::API::Category::DuplicateValueError.new(
+                    "Constant #{category_const} is already defined in #{self.name}") if self.const_defined?(category_const)
+
+                  new_instance = self.new(category_value)
+                  self.const_set(category_const, new_instance)
+
+                  define_method "#{category_value}?".to_sym do
+                    value.eql?(category_value)
+                  end
+
+                  categories[new_instance.name]                     ||= {}
+                  categories[new_instance.name][new_instance.value] = new_instance
+                end
+              end
+            end
+          end
+        end
+
+        attr_accessor :name, :value
+
+        def initialize(value)
+          raise ::Shippo::Exceptions::AbstractClassInitError.new('Can not instantiate Base!') if self.class.eql?(::Shippo::API::Category::Base)
+          self.name = Category.key(self.class.name.gsub(%r{.*::}, ''))
+          self.value = assign_value(value)
+        end
+
+        def eql?(other)
+          self.class.eql?(other.class) && self.value.eql?(other.value)
+        end
+
+        def to_s
+          "#{self.value.upcase}"
+        end
+
+        private
+
+        def value_allowed?(value)
+          self.class.allowed_values.include?(value)
+        end
+
+        def assign_value(value)
+          value = clean(value)
+
+          if value_allowed?(value)
+            @value = value
+          else
+            raise ::Shippo::Exceptions::InvalidCategoryValueError.new(
+              "Value #{value} is not allowed for Category #{self.class.name}, allowed values are: #{self.class.allowed_values})")
+          end
+          @value
+        end
+
+        def clean(value)
+          Category.key(value)
+        end
+
+      end
+    end
+  end
+end