reactive_shipping 3.0.0

data/lib/reactive_shipping/external_return_label_response.rb

@@ -0,0 +1,26 @@
+module ReactiveShipping #:nodoc:
+
+  class ExternalReturnLabelResponse < Response
+    attr_reader :carrier # symbol
+    attr_reader :carrier_name # string
+    attr_reader :tracking_number # string
+    attr_reader :return_label # string
+    attr_reader :postal_routing # string
+
+    def initialize(success, message, params = {}, options = {})
+      @carrier = options[:carrier].parameterize.to_sym
+      @carrier_name = options[:carrier]
+      @return_label = options[:return_label]
+      @tracking_number = options[:tracking_number]
+      @postal_routing = options[:postal_routing]
+      super
+    end
+
+    def has_exception?
+      @status == :exception
+    end
+
+    alias_method(:exception?, :has_exception?)
+  end
+
+end

data/lib/reactive_shipping/label.rb

@@ -0,0 +1,10 @@
+module ReactiveShipping
+  class Label
+    attr_reader :tracking_number, :img_data
+
+    def initialize(tracking_number, img_data)
+      @tracking_number = tracking_number
+      @img_data = img_data
+    end
+  end
+end

data/lib/reactive_shipping/label_response.rb

@@ -0,0 +1,10 @@
+module ReactiveShipping
+  class LabelResponse < Response
+    attr_reader :labels
+
+    def initialize(success, message, params = {}, options = {})
+      @labels = options[:labels]
+      super
+    end
+  end
+end

data/lib/reactive_shipping/location.rb

@@ -0,0 +1,166 @@
+module ReactiveShipping #:nodoc:
+  class Location
+    ADDRESS_TYPES = %w(residential commercial po_box)
+
+    ATTRIBUTE_ALIASES = {
+      name: [:name],
+      country: [:country_code, :country],
+      postal_code: [:postal_code, :zip, :postal],
+      province: [:province_code, :state_code, :territory_code, :region_code, :province, :state, :territory, :region],
+      city: [:city, :town],
+      address1: [:address1, :address, :street],
+      address2: [:address2],
+      address3: [:address3],
+      phone: [:phone, :phone_number],
+      fax: [:fax, :fax_number],
+      email: [:email],
+      address_type: [:address_type],
+      company_name: [:company, :company_name],
+    }.freeze
+
+    attr_reader :options,
+                :country,
+                :postal_code,
+                :province,
+                :city,
+                :name,
+                :address1,
+                :address2,
+                :address3,
+                :phone,
+                :fax,
+                :email,
+                :address_type,
+                :company_name
+
+    alias_method :zip, :postal_code
+    alias_method :postal, :postal_code
+    alias_method :state, :province
+    alias_method :territory, :province
+    alias_method :region, :province
+    alias_method :company, :company_name
+
+    def initialize(options = {})
+      @country = if options[:country].nil? || options[:country].is_a?(ActiveUtils::Country)
+        options[:country]
+      else
+        ActiveUtils::Country.find(options[:country])
+      end
+
+      @postal_code = options[:postal_code] || options[:postal] || options[:zip]
+      @province = options[:province] || options[:state] || options[:territory] || options[:region]
+      @city = options[:city]
+      @name = options[:name]
+      @address1 = options[:address1]
+      @address2 = options[:address2]
+      @address3 = options[:address3]
+      @phone = options[:phone]
+      @fax = options[:fax]
+      @email = options[:email]
+      @company_name = options[:company_name] || options[:company]
+
+      self.address_type = options[:address_type]
+    end
+
+    def self.from(object, options = {})
+      return object if object.is_a?(ReactiveShipping::Location)
+
+      attributes = {}
+
+      hash_access = object.respond_to?(:[])
+
+      ATTRIBUTE_ALIASES.each do |attribute, aliases|
+        aliases.detect do |sym|
+          value = object[sym] if hash_access
+          if !value &&
+            object.respond_to?(sym) &&
+            (!hash_access || !Hash.public_instance_methods.include?(sym))
+            value = object.send(sym)
+          end
+
+          attributes[attribute] = value if value
+        end
+      end
+
+      attributes.delete(:address_type) unless ADDRESS_TYPES.include?(attributes[:address_type].to_s)
+
+      new(attributes.update(options))
+    end
+
+    def country_code(format = :alpha2)
+      @country.nil? ? nil : @country.code(format).value
+    end
+
+    def residential?
+      @address_type == 'residential'
+    end
+
+    def commercial?
+      @address_type == 'commercial'
+    end
+
+    def po_box?
+      @address_type == 'po_box'
+    end
+
+    def unknown?
+      country_code == 'ZZ'
+    end
+
+    def address_type=(value)
+      return unless value.present?
+      raise ArgumentError.new("address_type must be one of #{ADDRESS_TYPES.join(', ')}") unless ADDRESS_TYPES.include?(value.to_s)
+      @address_type = value.to_s
+    end
+
+    def to_hash
+      {
+        country: country_code,
+        postal_code: postal_code,
+        province: province,
+        city: city,
+        name: name,
+        address1: address1,
+        address2: address2,
+        address3: address3,
+        phone: phone,
+        fax: fax,
+        email: email,
+        address_type: address_type,
+        company_name: company_name
+      }
+    end
+
+    def to_s
+      prettyprint.gsub(/\n/, ' ')
+    end
+
+    def prettyprint
+      chunks = [@name, @address1, @address2, @address3]
+      chunks << [@city, @province, @postal_code].reject(&:blank?).join(', ')
+      chunks << @country
+      chunks.reject(&:blank?).join("\n")
+    end
+
+    def inspect
+      string = prettyprint
+      string << "\nPhone: #{@phone}" unless @phone.blank?
+      string << "\nFax: #{@fax}" unless @fax.blank?
+      string << "\nEmail: #{@email}" unless @email.blank?
+      string
+    end
+
+    # Returns the postal code as a properly formatted Zip+4 code, e.g. "77095-2233"
+    def zip_plus_4
+      "#{$1}-#{$2}" if /(\d{5})-?(\d{4})/ =~ @postal_code
+    end
+
+    def address2_and_3
+      [address2, address3].reject(&:blank?).join(", ")
+    end
+
+    def ==(other)
+      to_hash == other.to_hash
+    end
+  end
+end

data/lib/reactive_shipping/package.rb

@@ -0,0 +1,165 @@
+module ReactiveShipping #:nodoc:
+  class Package
+    cattr_accessor :default_options
+    attr_reader :options, :value, :currency
+
+    # Package.new(100, [10, 20, 30], :units => :metric)
+    # Package.new(Measured::Weight.new(100, :g), [10, 20, 30].map {|m| Length.new(m, :centimetres)})
+    # Package.new(100.grams, [10, 20, 30].map(&:centimetres))
+    def initialize(grams_or_ounces, dimensions, options = {})
+      options = @@default_options.update(options) if @@default_options
+      options.symbolize_keys!
+      @options = options
+
+      @dimensions = [dimensions].flatten.reject(&:nil?)
+
+      imperial = (options[:units] == :imperial)
+
+      weight_imperial = dimensions_imperial = imperial if options.include?(:units)
+
+      if options.include?(:weight_units)
+        weight_imperial = (options[:weight_units] == :imperial)
+      end
+
+      if options.include?(:dim_units)
+        dimensions_imperial = (options[:dim_units] == :imperial)
+      end
+
+      @weight_unit_system = weight_imperial ? :imperial : :metric
+      @dimensions_unit_system = dimensions_imperial ? :imperial : :metric
+
+      @weight = attribute_from_metric_or_imperial(grams_or_ounces, Measured::Weight, @weight_unit_system, :grams, :ounces)
+
+      if @dimensions.blank?
+        zero_length = Measured::Length.new(0, (dimensions_imperial ? :inches : :centimetres))
+        @dimensions = [zero_length] * 3
+      else
+        process_dimensions
+      end
+
+      @value = Package.cents_from(options[:value])
+      @currency = options[:currency] || (options[:value].currency if options[:value].respond_to?(:currency))
+      @cylinder = (options[:cylinder] || options[:tube]) ? true : false
+      @gift = options[:gift] ? true : false
+      @oversized = options[:oversized] ? true : false
+      @unpackaged = options[:unpackaged] ? true : false
+    end
+
+    def unpackaged?
+      @unpackaged
+    end
+
+    def oversized?
+      @oversized
+    end
+
+    def cylinder?
+      @cylinder
+    end
+    alias_method :tube?, :cylinder?
+
+    def gift?
+      @gift
+    end
+
+    def ounces(options = {})
+      weight(options).convert_to(:oz).value.to_f
+    end
+    alias_method :oz, :ounces
+
+    def grams(options = {})
+      weight(options).convert_to(:g).value.to_f
+    end
+    alias_method :g, :grams
+
+    def pounds(options = {})
+      weight(options).convert_to(:lb).value.to_f
+    end
+    alias_method :lb, :pounds
+    alias_method :lbs, :pounds
+
+    def kilograms(options = {})
+      weight(options).convert_to(:kg).value.to_f
+    end
+    alias_method :kg, :kilograms
+    alias_method :kgs, :kilograms
+
+    def inches(measurement = nil)
+      @inches ||= @dimensions.map { |m| m.convert_to(:in).value.to_f }
+      measurement.nil? ? @inches : measure(measurement, @inches)
+    end
+    alias_method :in, :inches
+
+    def centimetres(measurement = nil)
+      @centimetres ||= @dimensions.map { |m| m.convert_to(:cm).value.to_f }
+      measurement.nil? ? @centimetres : measure(measurement, @centimetres)
+    end
+    alias_method :cm, :centimetres
+
+    def weight(options = {})
+      case options[:type]
+      when nil, :actual
+        @weight
+      when :volumetric, :dimensional
+        @volumetric_weight ||= begin
+          m = Measured::Weight.new((centimetres(:box_volume) / 6.0), :grams)
+          @weight_unit_system == :imperial ? m.convert_to(:oz) : m
+        end
+      when :billable
+        [weight, weight(:type => :volumetric)].max
+      end
+    end
+    alias_method :mass, :weight
+
+    def self.cents_from(money)
+      return nil if money.nil?
+      if money.respond_to?(:cents)
+        return money.cents
+      else
+        case money
+        when Float
+          (money * 100).round
+        when String
+          money =~ /\./ ? (money.to_f * 100).round : money.to_i
+        else
+          money.to_i
+        end
+      end
+    end
+
+    private
+
+    def attribute_from_metric_or_imperial(obj, klass, unit_system, metric_unit, imperial_unit)
+      if obj.is_a?(klass)
+        return obj
+      else
+        return klass.new(obj, (unit_system == :imperial ? imperial_unit : metric_unit))
+      end
+    end
+
+    def measure(measurement, ary)
+      case measurement
+      when Integer then ary[measurement]
+      when :x, :max, :length, :long then ary[2]
+      when :y, :mid, :width, :wide then ary[1]
+      when :z, :min, :height, :depth, :high, :deep then ary[0]
+      when :girth, :around, :circumference
+        self.cylinder? ? (Math::PI * (ary[0] + ary[1]) / 2) : (2 * ary[0]) + (2 * ary[1])
+      when :volume then self.cylinder? ? (Math::PI * (ary[0] + ary[1]) / 4)**2 * ary[2] : measure(:box_volume, ary)
+      when :box_volume then ary[0] * ary[1] * ary[2]
+      end
+    end
+
+    def process_dimensions
+      @dimensions = @dimensions.map do |l|
+        attribute_from_metric_or_imperial(l, Measured::Length, @dimensions_unit_system, :centimetres, :inches)
+      end.sort
+      # [1,2] => [1,1,2]
+      # [5] => [5,5,5]
+      # etc..
+      2.downto(@dimensions.length) do |_n|
+        @dimensions.unshift(@dimensions[0])
+      end
+    end
+  end
+end

data/lib/reactive_shipping/package_item.rb

@@ -0,0 +1,60 @@
+module ReactiveShipping #:nodoc:
+  class PackageItem
+    attr_reader :sku, :hs_code, :value, :name, :weight, :quantity, :options
+
+    def initialize(name, grams_or_ounces, value, quantity, options = {})
+      @name = name
+
+      imperial = (options[:units] == :imperial)
+
+      @unit_system = imperial ? :imperial : :metric
+
+      @weight = grams_or_ounces
+      @weight = Measured::Weight.new(grams_or_ounces, (@unit_system == :imperial ? :oz : :g)) unless @weight.is_a?(Measured::Weight)
+
+      @value = Package.cents_from(value)
+      @quantity = quantity > 0 ? quantity : 1
+
+      @sku = options[:sku]
+      @hs_code = options[:hs_code]
+      @options = options
+    end
+
+    def weight(options = {})
+      case options[:type]
+      when nil, :actual
+        @weight
+      when :volumetric, :dimensional
+        @volumetric_weight ||= begin
+          m = Measured::Weight.new((centimetres(:box_volume) / 6.0), :grams)
+          @unit_system == :imperial ? m.in_ounces : m
+        end
+      when :billable
+        [weight, weight(:type => :volumetric)].max
+      end
+    end
+    alias_method :mass, :weight
+
+    def ounces(options = {})
+      weight(options).convert_to(:oz).value
+    end
+    alias_method :oz, :ounces
+
+    def grams(options = {})
+      weight(options).convert_to(:g).value
+    end
+    alias_method :g, :grams
+
+    def pounds(options = {})
+      weight(options).convert_to(:lb).value
+    end
+    alias_method :lb, :pounds
+    alias_method :lbs, :pounds
+
+    def kilograms(options = {})
+      weight(options).convert_to(:kg).value
+    end
+    alias_method :kg, :kilograms
+    alias_method :kgs, :kilograms
+  end
+end

data/lib/reactive_shipping/rate_estimate.rb

@@ -0,0 +1,197 @@
+module ReactiveShipping
+
+  # Class representing a shipping option with estimated price.
+  #
+  # @!attribute origin
+  #   The origin of the shipment
+  #   @return [ReactiveShipping::Location]
+  #
+  # @!attribute destination
+  #   The destination of the shipment
+  #   @return [ReactiveShipping::Location]
+  #
+  # @!attribute package_rates
+  #   A list of rates for all the packages in the shipment
+  #   @return [Array<{:rate => Integer, :package => ReactiveShipping::Package}>]
+  #
+  # @!attribute carrier
+  #   The name of the carrier (e.g. 'USPS', 'FedEx')
+  #   @return [String]
+  #   @see ReactiveShipping::Carrier.name
+  #
+  # @!attribute service_name
+  #   The name of the shipping service (e.g. 'First Class Ground')
+  #   @return [String]
+  #
+  # @!attribute service_code
+  #   The code of the shipping service
+  #   @return [String]
+  #
+  # @!attribute description
+  #   Public description of the shipping service (e.g. '2 days delivery')
+  #   @return [String]
+  #
+  # @!attribute shipping_date
+  #   The date on which the shipment will be expected. Normally, this means that the
+  #   delivery date range can only be promised if the shipment is handed over on or
+  #   before this date.
+  #   @return [Date]
+  #
+  # @!attribute delivery_date
+  #   The date on which the shipment will be delivered. This is usually only available
+  #   for express shipments; in other cases a {#delivery_range} is given instead.
+  #   @return [Date]
+  #
+  # @!attribute delivery_range
+  #   The minimum and maximum date of when the shipment is expected to be delivered
+  #   @return [Array<Date>]
+  #
+  # @!attribute currency
+  #   ISO4217 currency code of the quoted rate estimates (e.g. `CAD`, `EUR`, or `USD`)
+  #   @return [String]
+  #   @see http://en.wikipedia.org/wiki/ISO_4217
+  #
+  # @!attribute negotiated_rate
+  #   The negotiated rate in cents
+  #   @return [Integer]
+  #
+  # @!attribute compare_price
+  #   The comparable price in cents
+  #   @return [Integer]
+  #
+  # @!attribute phone_required
+  #   Specifies if a phone number is required for the shipping rate
+  #   @return [Boolean]
+  #
+  # @!attribute insurance_price
+  #   The price of insurance in cents
+  #   @return [Integer]
+  #
+  # @!attribute delivery_category
+  #   The general classification of the delivery method
+  #   @return [String]
+  #
+  # @!attribute shipment_options
+  #   Additional priced options bundled with the given rate estimate with price in cents
+  #   @return [Array<{ code: String, price: Integer }>]
+  #
+  # @!attribute charge_items
+  #   Breakdown of a shipping rate's price with amounts in cents.
+  #   @return [Array<{ group: String, code: String, name: String, description: String, amount: Integer }>]
+  #
+  class RateEstimate
+    attr_accessor :origin, :destination, :package_rates,
+                :carrier, :service_name, :service_code, :description,
+                :shipping_date, :delivery_date, :delivery_range,
+                :currency, :negotiated_rate, :insurance_price,
+                :estimate_reference, :expires_at, :pickup_time,
+                :compare_price, :phone_required, :delivery_category,
+                :shipment_options, :charge_items, :messages
+
+    def initialize(origin, destination, carrier, service_name, options = {})
+      self.origin, self.destination, self.carrier, self.service_name = origin, destination, carrier, service_name
+      self.service_code = options[:service_code]
+      self.description = options[:description]
+      self.estimate_reference = options[:estimate_reference]
+      self.pickup_time = options[:pickup_time]
+      self.expires_at = options[:expires_at]
+      if options[:package_rates]
+        self.package_rates = options[:package_rates].map { |p| p.update(:rate => Package.cents_from(p[:rate])) }
+      else
+        self.package_rates = Array(options[:packages]).map { |p| {:package => p} }
+      end
+      self.total_price = options[:total_price]
+      self.negotiated_rate = options[:negotiated_rate]
+      self.compare_price = options[:compare_price]
+      self.phone_required = options[:phone_required]
+      self.currency = options[:currency]
+      self.delivery_range = options[:delivery_range]
+      self.shipping_date = options[:shipping_date]
+      self.delivery_date = @delivery_range.last
+      self.insurance_price = options[:insurance_price]
+      self.delivery_category = options[:delivery_category]
+      self.shipment_options = options[:shipment_options] || []
+      self.charge_items = options[:charge_items] || []
+      self.messages = options[:messages] || []
+    end
+
+    # The total price of the shipments in cents.
+    # @return [Integer]
+    def total_price
+      @total_price || @package_rates.sum { |pr| pr[:rate] }
+    rescue NoMethodError
+      raise ArgumentError.new("RateEstimate must have a total_price set, or have a full set of valid package rates.")
+    end
+    alias_method :price, :total_price
+
+    # Adds a package to this rate estimate
+    # @param package [ReactiveShipping::Package] The package to add.
+    # @param rate [#cents, Float, String, nil] The rate for this package. This is only required if
+    #   there is no total price for this shipment
+    # @return [self]
+    def add(package, rate = nil)
+      cents = Package.cents_from(rate)
+      raise ArgumentError.new("New packages must have valid rate information since this RateEstimate has no total_price set.") if cents.nil? and total_price.nil?
+      @package_rates << {:package => package, :rate => cents}
+      self
+    end
+
+    # The list of packages for which rate estimates are given.
+    # @return [Array<ReactiveShipping::Package>]
+    def packages
+      package_rates.map { |p| p[:package] }
+    end
+
+    # The number of packages for which rate estimates are given.
+    # @return [Integer]
+    def package_count
+      package_rates.length
+    end
+
+    protected
+
+    def delivery_range=(delivery_range)
+      @delivery_range = delivery_range ? delivery_range.map { |date| date_for(date) }.compact : []
+    end
+
+    def total_price=(total_price)
+      @total_price = Package.cents_from(total_price)
+    end
+
+    def negotiated_rate=(negotiated_rate)
+      @negotiated_rate = negotiated_rate ? Package.cents_from(negotiated_rate) : nil
+    end
+
+    def compare_price=(compare_price)
+      @compare_price = compare_price ? Package.cents_from(compare_price) : nil
+    end
+
+    def currency=(currency)
+      @currency = ActiveUtils::CurrencyCode.standardize(currency)
+    end
+
+    def phone_required=(phone_required)
+      @phone_required = !!phone_required
+    end
+
+    def shipping_date=(shipping_date)
+      @shipping_date = date_for(shipping_date)
+    end
+
+    def insurance_price=(insurance_price)
+      @insurance_price = Package.cents_from(insurance_price)
+    end
+
+    private
+
+    # Returns a Date object for a given input
+    # @param date [String, Date, Time, DateTime, ...] The object to infer a date from.
+    # @return [Date, nil] The Date object absed on the input, or `nil` if no date
+    #   could be determined.
+    def date_for(date)
+      date && Date.strptime(date.to_s, "%Y-%m-%d")
+    rescue ArgumentError
+      nil
+    end
+  end
+end