stamps 0.2.0

data/lib/stamps/configuration.rb

@@ -0,0 +1,69 @@
+module Stamps
+  # Defines constants and methods related to configuration
+  module Configuration
+
+    # An array of valid keys in the options hash when configuring a {Twitter::API}
+    VALID_OPTIONS_KEYS = [
+      :integration_id,
+      :username,
+      :password,
+      :namespace,
+      :format,
+      :return_address,
+      :test_mode,
+      :raise_errors,
+      :log_messages,
+      :endpoint].freeze
+
+    # The endpoint that will be used to connect if none is set
+    DEFAULT_ENDPOINT = 'https://swsim.testing.stamps.com/swsim/swsimv12.asmx'.freeze
+
+    # The default namespace used on Stamps.com wsdl
+    DEFAULT_NAMESPACE = 'http://stamps.com/xml/namespace/2010/11/swsim/swsimv12'
+
+    # @note JSON is preferred over XML because it is more concise and faster to parse.
+    DEFAULT_FORMAT = :hash
+
+    # The user agent that will be sent to the API endpoint if none is set
+    DEFAULT_USER_AGENT = "Stamps Ruby Gem".freeze
+
+    # Do not raise errors by default
+    DEFAULT_RAISE_ERRORS = false
+
+    # Do not log requests and response by default
+    DEFAULT_LOG_MESSAGES = false
+
+    # @private
+    attr_accessor *VALID_OPTIONS_KEYS
+
+    # When this module is extended, set all configuration options to their default values
+    def self.extended(base)
+      base.reset
+    end
+
+    # Convenience method to allow configuration options to be set in a block
+    def configure
+      yield self
+
+      HTTPI.log = false
+      Savon.configure do |config|
+        config.log = self.log_messages
+        config.raise_errors = self.raise_errors
+      end
+    end
+
+    # Create a hash of options and their values
+    def options
+      Hash[VALID_OPTIONS_KEYS.map {|key| [key, send(key)] }]
+    end
+
+    # Reset all configuration options to defaults
+    def reset
+      self.endpoint     = DEFAULT_ENDPOINT
+      self.namespace    = DEFAULT_NAMESPACE
+      self.format       = DEFAULT_FORMAT
+      self.log_messages = DEFAULT_LOG_MESSAGES
+      self.raise_errors = DEFAULT_RAISE_ERRORS
+    end
+  end
+end

data/lib/stamps/errors.rb

@@ -0,0 +1,34 @@
+module Stamps
+
+  # Custom error class for rescuing from all Stamps.com errors
+  class Error < StandardError
+    attr_reader :data
+
+    def initialize(data)
+      @data = data
+      super
+    end
+  end
+
+  # Raised when Stamps.com returns the HTTP status code 400
+  class BadRequest < Error; end
+
+  # Raised when Stamps.com returns the HTTP status code 401
+  class Unauthorized < Error; end
+
+  # Raised when Stamps.com returns the HTTP status code 403
+  class Forbidden < Error; end
+
+  # Raised when Stamps.com returns the HTTP status code 404
+  class NotFound < Error; end
+
+  # Raised when Stamps.com returns the HTTP status code 406
+  class NotAcceptable < Error; end
+
+  # Raised when Stamps.com returns the HTTP status code 500
+  class InternalServerError < Error; end
+
+  # Raised when Stamps.com returns the HTTP status code 503
+  class ServiceUnavailable < Error; end
+
+end

data/lib/stamps/mapping.rb

@@ -0,0 +1,247 @@
+module Stamps
+
+  # == Mapping Module
+  #
+  # Provides an interface to convert hash keys and values into a
+  # hash that can be easily coverted to an xml document that the
+  # web service can understand.
+  #
+  #
+  module Mapping
+
+    class Account < Hashie::Trash
+      property :Authenticator, :from => :authenticator
+    end
+
+    class AuthenticateUser < Hashie::Trash
+      property :Credentials,   :from => :credentials
+
+      def credentials=(val)
+        self[:Credentials] = Credentials.new(val)
+      end
+    end
+
+    class Credentials < Hashie::Trash
+      property :IntegrationID, :from => :integration_id
+      property :Username,      :from => :username
+      property :Password,      :from => :password
+    end
+
+    class Rates < Hashie::Trash
+      property :Authenticator, :from => :authenticator
+      property :Rate,          :from => :rate
+    end
+
+    class Rate < Hashie::Trash
+      property :FromZIPCode,             :from => :from_zip_code
+      property :ToZIPCode,               :from => :to_zip_code
+      property :ToCountry,               :from => :to_country
+      property :Amount,                  :from => :amount
+      property :MaxAmount,               :from => :max_amount
+      property :ServiceType,             :from => :service_type
+      property :PrintLayout,             :from => :print_layout
+      property :DeliverDays,             :from => :deliver_days
+      property :Error,                   :from => :error
+      property :WeightLb,                :from => :weight_lb
+      property :WeightOz,                :from => :weight_oz
+      property :PackageType,             :from => :package_type
+      property :RequiresAllOf,           :from => :requires_all
+      property :Length,                  :from => :length
+      property :Width,                   :from => :width
+      property :Height,                  :from => :height
+      property :ShipDate,                :from => :ship_date
+      property :InsuredValue,            :from => :insured_value
+      property :RegisteredValue,         :from => :registration_value
+      property :CODValue,                :from => :cod_value
+      property :DeclaredValue,           :from => :declared_value
+      property :NonMachinable,           :from => :non_machinable
+      property :RectangularShaped,       :from => :rectangular
+      property :Prohibitions,            :from => :prohibitions
+      property :Restrictions,            :from => :restrictions
+      property :Observations,            :from => :observations
+      property :Regulations,             :from => :regulations
+      property :GEMNotes,                :from => :gem_notes
+      property :MaxDimensions,           :from => :max_dimensions
+      property :DimWeighting,            :from => :dim_weighting
+      property :AddOns,                  :from => :add_ons
+      property :EffectiveWeightInOunces, :from => :effective_weight_in_ounces
+      property :IsIntraBMC,              :from => :is_intra_bmc
+      property :Zone,                    :from => :zone
+      property :RateCategory,            :from => :rate_category
+      property :ToState,                 :from => :to_state
+      property :CubicPricing,            :from => :cubic_pricing
+
+      # Maps :rate to AddOns map
+      def add_ons=(addons)
+        self[:AddOns] = AddOnsArray.new(:add_on => addons[:add_on])
+      end
+    end
+
+    class AddOnsArray < Hashie::Trash
+      property :AddOnV2,     :from => :add_on
+      def add_on=(vals)
+        return unless vals
+        self[:AddOnV2] = vals.map{ |value| AddOnV2.new(value).to_hash }
+      end
+    end
+
+    class AddOnV2 < Hashie::Trash
+      property :Amount,                    :from => :amount
+      property :AddOnType,                 :from => :type
+    end
+
+    class Stamp < Hashie::Trash
+      property :Authenticator,                        :from => :authenticator
+      property :IntegratorTxID,                       :from => :transaction_id
+      property :TrackingNumber,                       :from => :tracking_number
+      property :Rate,                                 :from => :rate
+      property :From,                                 :from => :from
+      property :To,                                   :from => :to
+      property :CustomerID,                           :from => :customer_id
+      property :Customs,                              :from => :customs
+      property :SampleOnly,                           :from => :sample
+      property :ImageType,                            :from => :image_type
+      property :EltronPrinterDPIType,                 :from => :label_resolution
+      property :memo
+      property :recipient_email,                      :from => :recipient_email
+      property :deliveryNotification,                 :from => :notify
+      property :shipmentNotificationCC,               :from => :notify_crates
+      property :shipmentNotificationFromCompany,      :from => :notify_from_company
+      property :shipmentNotificationCompanyInSubject, :from => :notify_in_subject
+      property :rotationDegrees,                      :from => :rotation
+      property :printMemo,                            :from => :print_memo
+
+      # Maps :from to Address map
+      def from=(val)
+        # Set the defult :from address from address
+        self[:From] = Address.new(Stamps.return_address.merge!(val))
+      end
+
+      # Maps :to to Address map
+      def to=(val)
+        self[:To] = Address.new(val)
+      end
+
+      # Maps :rate to Rate map
+      def rate=(val)
+        self[:Rate] = Rate.new(val)
+      end
+
+      # Maps :customs to Customs map
+      def customs=(val)
+        self[:Customs] = Customs.new(val)
+      end
+    end
+
+    class Address < Hashie::Trash
+      property :FullName,     :from => :full_name
+      property :NamePrefix,   :from => :name_prefix
+      property :FirstName,    :from => :first_name
+      property :MiddleName,   :from => :middle_name
+      property :LastName,     :from => :last_name
+      property :NameSuffix,   :from => :name_suffex
+      property :Title,        :from => :title
+      property :Department,   :from => :deparartment
+      property :Company,      :from => :company
+      property :Address1,     :from => :address1
+      property :Address2,     :from => :address2
+      property :City,         :from => :city
+      property :State,        :from => :state
+      property :ZIPCode,      :from => :zip_code
+      property :ZIPCodeAddOn, :from => :zip_code_add_on
+      property :DPB,          :from => :dpb
+      property :CheckDigit,   :from => :check_digit
+      property :Province,     :from => :province
+      property :PostalCode,   :from => :postal_code
+      property :Country,      :from => :country
+      property :Urbanization, :from => :urbanization
+      property :PhoneNumber,  :from => :phone_number
+      property :Extension,    :from => :extentsion
+      property :CleanseHash,  :from => :cleanse_hash
+      property :OverrideHash, :from => :override_hash
+    end
+
+    class CleanseAddress < Hashie::Trash
+      property :Authenticator, :from => :authenticator
+      property :Address,       :from => :address
+
+      # Maps :address to Address map
+      def address=(val)
+        self[:Address] = Address.new(val)
+      end
+    end
+
+    class PurchasePostage < Hashie::Trash
+      property :Authenticator,  :from => :authenticator
+      property :PurchaseAmount, :from => :amount
+      property :ControlTotal,   :from => :control_total
+    end
+
+    class CancelStamp< Hashie::Trash
+      property :Authenticator,  :from => :authenticator
+      property :StampsTxID,     :from => :transaction_id
+      property :TrackingNumber, :from => :tracking_number
+    end
+
+    class CarrierPickup < Hashie::Trash
+      property :Authenticator,               :from => :authenticator
+      property :FirstName,                   :from => :first_name
+      property :LastName,                    :from => :last_name
+      property :Company,                     :from => :company
+      property :Address,                     :from => :address
+      property :SuiteOrApt,                  :from => :suite,  :default => ''
+      property :City,                        :from => :city
+      property :State,                       :from => :state
+      property :ZIP,                         :from => :zip
+      property :ZIP4,                        :from => :zip_four
+      property :PhoneNumber,                 :from => :phone
+      property :PhoneExt,                    :from => :phone_ext
+      property :NumberOfExpressMailPieces,   :from => :express_mail_count
+      property :NumberOfPriorityMailPieces,  :from => :priority_mail_count
+      property :NumberOfInternationalPieces, :from => :international_mail_count
+      property :NumberOfOtherPieces,         :from => :other_mail_count
+      property :TotalWeightOfPackagesLbs,    :from => :total_weight
+      property :PackageLocation,             :from => :location
+      property :SpecialInstruction,          :from => :special_instruction
+    end
+
+    class Customs < Hashie::Trash
+      property :ContentType,       :from => :content_type
+      property :Comments,          :from => :comments
+      property :LicenseNumber,     :from => :license_number
+      property :CertificateNumber, :from => :certificate_number
+      property :InvoiceNumber,     :from => :invoice_number
+      property :OtherDescribe,     :from => :other_describe
+      property :CustomsLines,      :from => :customs_lines
+
+      # Maps :customs CustomsLine map
+      def customs_lines=(customs)
+        # Important:  Must call to_hash to force re-ordering!
+        self[:CustomsLines] = customs.collect{ |val| CustomsLinesArray.new(val).to_hash }
+      end
+    end
+
+    class CustomsLinesArray < Hashie::Trash
+      property :CustomsLine,     :from => :custom
+      def custom=(val)
+        self[:CustomsLine] = CustomsLine.new(val).to_hash
+      end
+    end
+
+    class CustomsLine < Hashie::Trash
+      property :Description,     :from => :description
+      property :Quantity,        :from => :quantity
+      property :Value,           :from => :value
+      property :WeightLb,        :from => :weight_lb
+      property :WeightOz,        :from => :weight_oz
+      property :HSTariffNumber,  :from => :hs_tariff_number
+      property :CountryOfOrigin, :from => :country_of_origin
+    end
+
+    class TrackShipment < Hashie::Trash
+      property :Authenticator, :from => :authenticator
+      property :StampsTxID,    :from => :stamps_transaction_id
+    end
+
+  end
+end

data/lib/stamps/request.rb

@@ -0,0 +1,55 @@
+require 'hashie'
+require 'savon'
+require File.expand_path('../response', __FILE__)
+
+module Stamps
+
+  # Defines HTTP request methods
+  module Request
+
+    # Perform an HTTP request
+    def request(web_method, params, raw=false)
+      client = Savon::Client.new do |wsdl, http|
+        wsdl.endpoint = self.endpoint
+        wsdl.namespace = self.namespace
+      end
+
+      response = client.request :tns, web_method do
+        http.headers = { "SoapAction" => formatted_soap_action(web_method) }
+        soap.namespace = 'tns'
+        soap.element_form_default = :qualified
+        soap.env_namespace = 'soap'
+        soap.namespaces["xmlns:tns"] = self.namespace
+        soap.body = params.to_hash
+      end
+      Stamps::Response.new(response).to_hash
+    end
+
+    # Get the Authenticator token. By using an Authenticator, the integration
+    # can be sure that the conversation between the integration and the SWS
+    # server is kept in sync and no messages have been lost.
+    #
+    def authenticator_token
+      @authenticator ||= self.get_authenticator_token
+    end
+
+    # Make Authentication request for the user
+    #
+    def get_authenticator_token
+      self.request('AuthenticateUser',
+        Stamps::Mapping::AuthenticateUser.new(
+          :credentials => {
+            :integration_id => self.integration_id,
+            :username       => self.username,
+            :password       => self.password
+        })
+      )[:authenticate_user_response][:authenticator]
+    end
+
+    # Concatenates namespace and web method in a way the API can understand
+    def formatted_soap_action(web_method)
+      [self.namespace, web_method.to_s].compact.join('/')
+    end
+
+  end
+end

data/lib/stamps/response.rb

@@ -0,0 +1,71 @@
+module Stamps
+
+  # = Stamps::Response
+  #
+  # Represents the response and contains the HTTP response.
+  #
+  class Response
+
+    # Expects an <tt>Savon::SOAP::Response</tt> and handles errors.
+    def initialize(response)
+      self.errors = []
+      self.valid = true
+      self.savon  = response
+      self.http   = response.http
+      self.hash   = self.savon.to_hash
+      raise_errors
+    end
+
+    attr_accessor :savon, :http, :errors, :valid, :hash, :code
+
+    # Returns the SOAP response body as a Hash.
+    def to_hash
+      self.hash.merge!(:errors => self.errors)
+      self.hash.merge!(:valid? => self.valid)
+      self.hash
+      Stamps.format.to_s.downcase == 'hashie' ? Hashie::Mash.new(@hash) : self.hash
+    end
+
+    # Um, there's gotta be a better way
+    def valid?
+      self.valid
+    end
+
+    # Process any errors we get back from the service.
+    # Wrap any internal errors (from Soap Faults) into an array
+    # so that clients can process the error messages as they wish
+    #
+    def raise_errors
+      message =  'FIXME:  Need to parse http for response message'
+      return  self.format_soap_faults if savon.soap_fault.present?
+
+      case http.code.to_i
+      when 200
+        return
+      when 400
+        raise BadRequest, "(#{http.code}): #{message}"
+      when 401
+        raise Unauthorized, "(#{http.code}): #{message}"
+      when 403
+        raise Forbidden, "(#{http.code}): #{message}"
+      when 404
+        raise NotFound, "(#{http.code}): #{message}"
+      when 406
+        raise NotAcceptable, "(#{http.code}): #{message}"
+      when 500
+        raise InternalServerError, "Stamps.com had an internal error. (#{http.code}): #{message}"
+      when 502..503
+        raise ServiceUnavailable, "(#{http.code}): #{message}"
+      end
+    end
+
+    # Include any errors in the response
+    #
+    def format_soap_faults
+      fault = self.hash.delete(:fault)
+      self.errors << fault[:faultstring]
+      self.valid = false
+    end
+
+  end
+end