binarylogic-shippinglogic 0.9.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,6 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg
+spec/fedex_credentials.yml

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Ben Johnson of Binary Logic
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,128 @@
+= Shippinglogic
+
+The goal of this library is to provide simple and straight forward interfaces to the various shipping web services: FedEx, UPS, USPS, etc. (Only FedEx is supported at this time)
+
+== Helpful links
+
+* <b>Documentation:</b> http://rdoc.info/projects/binarylogic/shippinglogic
+* <b>Repository:</b> http://github.com/binarylogic/shippinglogic/tree/master
+* <b>Bugs / feature suggestions:</b> http://binarylogic.lighthouseapp.com/projects/16601-searchlogic
+* <b>Google group:</b> http://groups.google.com/group/shippinglogic
+
+<b>Before contacting me directly, please read:</b>
+
+If you find a bug or a problem please post it on lighthouse. If you need help with something, please use google groups. I check both regularly and get emails when anything happens, so that is the best place to get help. This also benefits other people in the future with the same questions / problems. Thank you.
+
+== Install & use
+
+Install the gem from rubyforge:
+
+  sudo gem install shippinglogic
+
+Or from github:
+
+  sudo gem install binarylogic-shippinglogic
+
+Now just include it in your project and you are ready to go.
+
+You can also install this as a plugin:
+
+  script/plugin install git://github.com/binarylogic/shippinglogic.git
+
+See below for usage examples.
+
+== Usage
+
+What's unique about this library is it's usage / syntax. Let me show you...
+
+=== Calls to the web services are lazy
+
+A simple example where we want to track a FedEx package:
+
+  fedex = Shippinglogic::FedEx.new(key, password, account, meter) # all credentials FedEx requires
+  tracking = fedex.track(:tracking_number => "077973360403984")
+
+Now here is why this is cool. Nothing has happened yet. No call has been made to the FedEx servers, etc. We do this because we don't need it yet. You don't need it until you start using the object. Lets continue with our example:
+
+  tracking.first  # call is made to FedEx and returns the first tracking result in the array
+  tracking.size   # cache is used to determine the size of the array
+
+This is similar to how ActiveRecord's association proxies work. When you call user.orders no database activity occurs until you actually use the object.
+
+=== Flexibility
+
+You will notice above we assign the result of the 'track' method to a variable called 'tracking'. That object has more to it:
+
+  # Initializing
+  tracking = fedex.track(:tracking_number => "XXXXXXXXXXXXX")
+  tracking.tracking_number
+  # => "XXXXXXXXXXXXX"
+  
+  # Attribute accessors
+  tracking.tracking_number = "YYYYYYYYYYYYYYY"
+  tracking.tracking_number
+  # => "YYYYYYYYYYYYYYY"
+  
+  # Mass attribute setting
+  tracking.attributes = {:tracking_number => "ZZZZZZZZZZZZZZZZ"}
+  tracking.tracking_number
+  # => "ZZZZZZZZZZZZZZZZ"
+  
+  # Mass attribute reading
+  tracking.attributes
+  # => {:tracking_number => "ZZZZZZZZZZZZZZZZ"}
+
+== Available services and their features
+
+This library is still very new, as a result only FedEx is support at this time. More will come.
+
+=== FedEx
+
+1. <b>Tracking</b> - See Shippinglogic::Fedex::Track
+1. <b>Getting service rates</b> - See Shippinglogic::Fedex::Rates
+
+=== Add your own services
+
+Simply fork the project and make your changes. If you want to add support for a new service it should be fairly straight forward. Checkout the code in Shippinglogic::Fedex::Track, it very simple and easy to follow. It's a great place to start because its the simplest of services.
+
+== Interface integration
+
+What's nice about having an object is that you can pass it around. Let's say you wanted to add simple FedEx tracking functionality to your app:
+
+  class TrackingController < ApplicationController
+    def new
+      @tracking = fedex.track(params[:tracking])
+    end
+    
+    def create
+      @tracking = fedex.track(params[:tracking])
+      render :action => :new if !@tracking.successful?
+    end
+    
+    private
+      def fedex
+        @fedex ||= Shippinglogic::FedEx.new(key, password, account, meter)
+      end
+  end
+
+That's pretty simple. Now check out your form:
+  
+  # new.html.haml
+  - form_for @tracking do |f|
+    = f.error_messages
+    = f.text_field :tracking_number
+    = f.submit "Track"
+
+Then your results:
+
+  # create.html.haml
+  - @tracking.each do |event|
+    .event
+      .name= event.name
+      .occured_at= event.occured_at.to_s(:long)
+      .location== #{event.city}, #{event.state} #{event.postal_code}, #{event.country}
+      .residential= event.residential ? "Yes" : "No"
+
+== Copyright
+
+Copyright (c) 2009 {Ben Johnson of Binary Logic}[http://www.binarylogic.com], released under the MIT license  

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "shippinglogic"
+    gem.summary = "A simple and clean library to interface with shipping carriers"
+    gem.description = "A simple and clean library to interface with shipping carriers"
+    gem.email = "bjohnson@binarylogic.com"
+    gem.homepage = "http://github.com/binarylogic/shippinglogic"
+    gem.authors = ["Ben Johnson of Binary Logic"]
+    gem.rubyforge_project = "shippinglogic"
+    gem.add_dependency "activesupport", ">= 2.2.0"
+    gem.add_dependency "httparty", ">= 0.4.4"
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+begin
+  require 'rake/contrib/sshpublisher'
+  namespace :rubyforge do
+    desc "Release gem to RubyForge"
+    task :release => ["rubyforge:release:gem"]
+  end
+rescue LoadError
+  puts "Rake SshDirPublisher is unavailable or your rubyforge environment is not configured."
+end
+

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:patch: 0
+:major: 0
+:minor: 9

data/lib/shippinglogic.rb

@@ -0,0 +1,3 @@
+require "httparty"
+require "activesupport"
+require "shippinglogic/fedex"

data/lib/shippinglogic/fedex.rb

@@ -0,0 +1,64 @@
+require "shippinglogic/fedex/error"
+require "shippinglogic/fedex/service"
+require "shippinglogic/fedex/rates"
+require "shippinglogic/fedex/track"
+
+module Shippinglogic
+  class FedEx
+    # A hash representing default the options. If you are using this in a Rails app the best place
+    # to modify or change these options is either in an initializer or your specific environment file. Keep
+    # in mind that these options can be modified on the instance level when creating an object. See #initialize
+    # for more details.
+    #
+    # === Options
+    #
+    # * <tt>:test</tt> - this basically tells us which url to use. If set to true we will use the FedEx test URL, if false we
+    #   will use the production URL. If you are using this in a rails app, unless you are in your production environment, this
+    #   will default to true automatically.
+    # * <tt>:test_url</tt> - the test URL for FedEx's webservices. (default: https://gatewaybeta.fedex.com:443/xml)
+    # * <tt>:production_url</tt> - the production URL for FedEx's webservices. (default: https://gateway.fedex.com:443/xml)
+    def self.options
+      @options ||= {
+        :test => defined?(Rails) && !Rails.env.production?,
+        :production_url => "https://gateway.fedex.com:443/xml",
+        :test_url => "https://gatewaybeta.fedex.com:443/xml"
+      }
+    end
+  
+    attr_accessor :key, :password, :account, :meter, :options
+  
+    # Before you can use the FedEx web services you need to provide 4 credentials:
+    #
+    # 1. Your fedex web service key
+    # 2. Your fedex password
+    # 3. Your fedex account number
+    # 4. Your fedex meter number
+    #
+    # You can easily get these things by logging into your fedex account and going to:
+    #
+    # https://www.fedex.com/wpor/wpor/editConsult.do
+    #
+    # If for some reason this link no longer works because FedEx changed it, just go to the
+    # developer resources area and then navigate to the FedEx web services for shipping area. Once
+    # there you should see a link to apply for a develop test key.
+    #
+    # The last parameter allows you to modify the class options on an instance level. It accepts the
+    # same options that the class level method #options accepts. If you don't want to change any of
+    # them, don't supply this parameter.
+    def initialize(key, password, account, meter, options = {})
+      self.key = key
+      self.password = password
+      self.account = account
+      self.meter = meter
+      self.options = self.class.options.merge(options)
+    end
+    
+    def rates(attributes = {})
+      @rates ||= Rates.new(self, attributes)
+    end
+    
+    def track(attributes = {})
+      @track ||= Track.new(self, attributes)
+    end
+  end
+end

data/lib/shippinglogic/fedex/attributes.rb

@@ -0,0 +1,118 @@
+module Shippinglogic
+  class FedEx
+    # Adds in all of the reading / writing for the various serivce options.
+    module Attributes
+      def self.included(klass)
+        klass.class_eval do
+          extend ClassMethods
+          include InstanceMethods
+        end
+      end
+      
+      module ClassMethods
+        # Define an attribute for a class, makes adding options / attributes to the class
+        # much cleaner. See the Rates class for an example.
+        def attribute(name, type, options = {})
+          name = name.to_sym
+          options[:type] = type.to_sym
+          attributes[name] = options
+          
+          define_method(name) { read_attribute(name) }
+          define_method("#{name}=") { |value| write_attribute(name, value) }
+        end
+        
+        # A hash of all the attributes and their options
+        def attributes
+          @attributes ||= {}
+        end
+        
+        # An array of the attribute names
+        def attribute_names
+          attributes.keys
+        end
+        
+        # Returns the options specified when defining a specific attribute
+        def attribute_options(name)
+          attributes[name.to_sym]
+        end
+      end
+      
+      module InstanceMethods
+        # A convenience so that you can set attributes while initializing an object
+        def initialize(base, attributes = {})
+          @attributes = {}
+          self.attributes = attributes
+        end
+        
+        # Returns a hash of the various attribute values
+        def attributes
+          attributes = {}
+          attribute_names.each do |name|
+            attributes[name] = send(name)
+          end
+          attributes
+        end
+        
+        # Accepts a hash of attribute values and sets each attribute to those values
+        def attributes=(value)
+          return if value.blank?
+          value.each do |key, value|
+            next if !attribute_names.include?(key.to_sym)
+            send("#{key}=", value)
+          end
+        end
+        
+        private
+          def attribute_names
+            self.class.attribute_names
+          end
+          
+          def attribute_options(name)
+            self.class.attribute_options(name)
+          end
+          
+          def attribute_type(name)
+            attribute_options(name)[:type]
+          end
+          
+          def attribute_default(name)
+            default = attribute_options(name)[:default]
+            case default
+            when Proc
+              default.call
+            else
+              default
+            end
+          end
+          
+          def write_attribute(name, value)
+            @attributes[name.to_sym] = value
+          end
+          
+          def read_attribute(name)
+            name = name.to_sym
+            value = @attributes[name].nil? ? attribute_default(name) : @attributes[name]
+            type = attribute_type(name)
+            return nil if value.nil? && type != :array
+            
+            case type
+            when :array
+              value.is_a?(Array) ? value : [value].compact
+            when :integer
+              value.to_i
+            when :float
+              value.to_f
+            when :big_decimal
+              BigDecimal.new(value)
+            when :boolean
+              ["true", "1"].include?(value.to_s)
+            when :string, :text
+              value.to_s
+            else
+              value
+            end
+          end
+      end
+    end
+  end
+end

data/lib/shippinglogic/fedex/error.rb

@@ -0,0 +1,47 @@
+module Shippinglogic
+  class FedEx
+    # If FedEx responds with an error, we try our best to pull the pertinent information out of that
+    # response and raise it with this object. Any time FedEx says there is a problem an object of this
+    # class will be raised.
+    #
+    # === Tip
+    #
+    # If you want to see the raw respose catch the error object and call the response method. Ex:
+    #
+    #   begin
+    #     # my fedex code
+    #   rescue Shippinglogic::FedEx::Error => e
+    #     # do whatever you want here, just do:
+    #     # e.response
+    #     # to get the raw response from fedex
+    #   end
+    class Error < StandardError
+      attr_accessor :code, :message, :response
+      
+      def initialize(response)
+        self.response = response
+        
+        if response.blank?
+          self.message = "The response from FedEx was blank."
+        elsif !response.is_a?(Hash)
+          self.message = "The response from FedEx was malformed and was not in a valid XML format."
+        elsif notifications = response[:notifications]
+          self.code = notifications[:code]
+          self.message = notifications[:message]
+        elsif response[:"soapenv:fault"] && detail = response[:"soapenv:fault"][:detail][:"con:fault"]
+          self.code = detail[:"con:error_code"]
+          self.message = detail[:"con:reason"]
+        else
+          self.message = "There was a problem with your fedex request, and we couldn't locate a specific error message. This means your response " +
+            "was in an unexpected format. You might try glancing at the raw response by using the 'response' method on this error object."
+        end
+        
+        error_message = ""
+        error_message += "(Error: #{code}) " if code
+        error_message = message
+        
+        super(error_message)
+      end
+    end
+  end
+end