fedex_ship 0.1.0

data/lib/fedex_ship/shipment.rb

@@ -0,0 +1,115 @@
+require 'fedex_ship/credentials'
+require 'fedex_ship/request/label'
+require 'fedex_ship/request/rate'
+require 'fedex_ship/request/tracking_information'
+require 'fedex_ship/request/address'
+require 'fedex_ship/request/document'
+require 'fedex_ship/request/delete'
+require 'fedex_ship/request/ground_close'
+require 'fedex_ship/request/pickup'
+require 'fedex_ship/request/pickup_availability'
+require 'fedex_ship/request/service_availability'
+
+module FedexShip
+  class Shipment
+
+    # In order to use Fedex rates API you must first apply for a developer(and later production keys),
+    # Visit {http://www.fedex.com/us/developer/ Fedex Developer Center} for more information about how to obtain your keys.
+    # @param [String] key - Fedex web service key
+    # @param [String] password - Fedex password
+    # @param [String] account_number - Fedex account_number
+    # @param [String] meter - Fedex meter number
+    # @param [String] mode - [development/production]
+    #
+    # return a FedexShip::Shipment object
+    def initialize(options={})
+      @credentials = Credentials.new(options)
+    end
+
+    # @param [Hash] shipper, A hash containing the shipper information
+    # @param [Hash] recipient, A hash containing the recipient information
+    # @param [Array] packages, An array including a hash for each package being shipped
+    # @param [String] service_type, A valid fedex service type, to view a complete list of services FedexShip::Shipment::SERVICE_TYPES
+    # @param [String] filename, A location where the label will be saved
+    # @param [Hash] label_specification, A hash containing the label printer settings
+    def label(options = {})
+      Request::Label.new(@credentials, options).process_request
+    end
+
+    # @param [Hash] shipper, A hash containing the shipper information
+    # @param [Hash] recipient, A hash containing the recipient information
+    # @param [Array] packages, An array including a hash for each package being shipped
+    # @param [String] service_type, A valid fedex service type, to view a complete list of services FedexShip::Shipment::SERVICE_TYPES
+    def rate(options = {})
+      Request::Rate.new(@credentials, options).process_request
+    end
+
+    # @param [Hash] address, A hash containing the address information
+    def validate_address(options = {})
+      Request::Address.new(@credentials, options).process_request
+    end
+
+    # @param [Hash] shipper, A hash containing the shipper information
+    # @param [Hash] recipient, A hash containing the recipient information
+    # @param [Array] packages, An array including a hash for each package being shipped
+    # @param [String] service_type, A valid fedex service type, to view a complete list of services FedexShip::Shipment::SERVICE_TYPES
+    def ship(options = {})
+      Request::Shipment.new(@credentials, options).process_request
+    end
+
+    # @param [String] carrier_code, A valid fedex carrier code, to view a complete list of carrier codes FedexShip::Shipment::CARRIER_CODES
+    # @param [Hash] packages, A hash containing the number of packages and their total weight
+    # @param [DateTime] ready_timestamp, A timestamp that indicates what day and time the package will be available for pickup
+    # @param [Time] close_time, The latest time that the business will be open to accept a pickup
+    # @param [Hash] pickup_location, A hash containing the pickup location information
+    def pickup(options = {})
+      Request::Pickup.new(@credentials, options).process_request
+    end
+
+    # @param [Hash] package_id, A string with the requested tracking number
+    # @param [Hash] package_type, A string identifitying the type of tracking number used. Full list FedexShip::Track::PACKAGE_IDENTIFIER_TYPES
+    def track(options = {})
+      Request::TrackingInformation.new(@credentials, options).process_request
+    end
+
+    # @param [Hash] shipper, A hash containing the shipper information
+    # @param [Hash] recipient, A hash containing the recipient information
+    # @param [Array] packages, An array including a hash for each package being shipped
+    # @param [String] service_type, A valid fedex service type, to view a complete list of services FedexShip::Shipment::SERVICE_TYPES
+    # @param [Hash] customs_clearance, A hash containing customs clearance specification
+    # @param [Hash] shipping_document, A hash containing shipping document specification
+    # @param [Array] filenames, A location where the label and shipment documents will be saved
+    def document(options = {})
+      Request::Document.new(@credentials, options).process_request
+    end
+
+    # @param [Hash] package_id, A string with the tracking number to delete
+    def delete(options = {})
+      Request::Delete.new(@credentials, options).process_request
+    end
+
+    # @param [Date] up_to_time, A time up to which shipments are to be closed
+    # @param [String] filename, A location where the manifest (text file) will be saved
+    def ground_close(options = {})
+      Request::GroundClose.new(@credentials, options).process_request
+    end
+    # @param [String] country_code, A string containing country code
+    # @param [String] state_code, A string containing state code
+    # @param [String] postal_code, A string containing postal code
+    # @param [String] carrier_code, A string containing carrier code
+    # @param [String] request_type, A string with request type
+    # @param [String] dispatch_date, A string with dispatch date in YYYY-MM-DD format
+    def pickup_availability(options = {})
+      Request::PickupAvailability.new(@credentials, options).process_request
+    end
+    
+    # param [Hash] origin, A hash containing origin information
+    # param [Hash] destination, A hash containing destination information
+    # param [date] ship_date, A string containing ship date in YYYY-MM-DD format
+    # param [String] carrier_code, A string containing carrier code
+    def service_availability(options = {})
+      Request::ServiceAvailability.new(@credentials, options).process_request
+    end
+
+  end
+end

data/lib/fedex_ship/tracking_information.rb

@@ -0,0 +1,54 @@
+require 'fedex_ship/tracking_information/event'
+
+module FedexShip
+  class TrackingInformation
+    PACKAGE_IDENTIFIER_TYPES = %w{
+      BILL_OF_LADING
+      COD_RETURN_TRACKING_NUMBER
+      CUSTOMER_AUTHORIZATION_NUMBER
+      CUSTOMER_REFERENCE
+      DEPARTMENT
+      FREE_FORM_REFERENCE
+      GROUND_INTERNATIONAL
+      GROUND_SHIPMENT_ID
+      GROUP_MPS
+      INVOICE
+      JOB_GLOBAL_TRACKING_NUMBER
+      ORDER_GLOBAL_TRACKING_NUMBER
+      ORDER_TO_PAY_NUMBER
+      PARTNER_CARRIER_NUMBER
+      PART_NUMBER
+      PURCHASE_ORDER
+      RETURN_MATERIALS_AUTHORIZATION
+      RETURNED_TO_SHIPPER_TRACKING_NUMBER
+      TRACKING_CONTROL_NUMBER
+      TRACKING_NUMBER_OR_DOORTAG
+      TRANSPORTATION_CONTROL_NUMBER
+      SHIPPER_REFERENCE
+      STANDARD_MPS
+    }
+
+    attr_reader :tracking_number, :signature_name, :service_type, :status, :status_code, :delivery_at, :events, :unique_tracking_number, :details, :other_identifiers
+
+    def initialize(details = {})
+      @details = details
+
+      @tracking_number        = details[:tracking_number]
+      @unique_tracking_number = details[:tracking_number_unique_identifier]
+      @signature_name         = details[:delivery_signature_name]
+      @service_type           = details[:service][:type]
+      @status                 = details[:status_detail][:description]
+      @status_code            = details[:status_detail][:code]
+      @other_identifiers      = details[:other_identifiers]
+
+      if details.has_key?(:actual_delivery_timestamp)
+        @delivery_at = Time.parse(details[:actual_delivery_timestamp])
+      end
+
+      @events = [details[:events]].flatten.compact.map do |event_details|
+        Event.new(event_details)
+      end
+    end
+
+  end
+end

data/lib/fedex_ship/tracking_information/event.rb

@@ -0,0 +1,24 @@
+module FedexShip
+  class TrackingInformation
+    class Event
+      attr_reader :description, :type, :occurred_at, :city, :state, :postal_code,
+                  :country, :residential, :exception_code, :exception_description
+
+      alias_method :occured_at, :occurred_at
+
+      def initialize(details = {})
+        @description           = details[:event_description]
+        @type                  = details[:event_type]
+        @occurred_at            = Time.parse(details[:timestamp])
+        @city                  = details[:address][:city]
+        @state                 = details[:address][:state_or_province_code]
+        @postal_code           = details[:address][:postal_code]
+        @country               = details[:address][:country_code]
+        @residential           = details[:address][:residential] == "true"
+        @exception_code        = details[:status_exception_code]
+        @exception_description = details[:status_exception_description]
+      end
+
+    end
+  end
+end

data/lib/fedex_ship/version.rb

@@ -0,0 +1,6 @@
+module FedexShip
+  VERSION = "0.1.0"
+  API_VERSION = "13"
+  PICKUP_API_VERSION = "17"
+  SERVICE_AVAILABILITY_API_VERSION = "5"
+end

data/spec/config/fedex_credentials.example.yml

@@ -0,0 +1,13 @@
+development:
+  :key: 'xxx' 
+  :password: 'xxx'
+  :account_number: 'xxx'
+  :meter: 'xxx' 
+  :mode: 'test' 
+  
+production:  
+  :key: 'xxx' 
+  :password: 'xxx'
+  :account_number: 'xxx'
+  :meter: 'xxx' 
+  :mode: 'production'

data/spec/lib/fedex_ship/address_spec.rb

@@ -0,0 +1,59 @@
+require 'spec_helper'
+
+module FedexShip
+  describe Address, :production do
+    describe "validation" do
+
+      # Address Validation is only enabled in the production environment
+      #
+      let(:fedex) { Shipment.new(fedex_production_credentials) }
+
+      context "valid address", :vcr do
+        let(:address) do
+          {
+            :address     => "5 Elm Street",
+            :city        => "Norwalk",
+            :state       => "CT",
+            :postal_code => "06850",
+            :country     => "USA"
+          }
+        end
+
+        let(:options) do
+          { :address => address }
+        end
+
+        it "validates the address" do
+          address = fedex.validate_address(options)
+
+          expect(address.residential).to be_truthy
+          expect(address.business).to    be_falsey
+          expect(address.score).to eq(100)
+
+          expect(address.postal_code).to eq("06850-3901")
+        end
+      end
+
+      context "multiple address validation results", :vcr do
+        let(:address) do
+          {
+            :address     => "301 Las Colinas Blvd",
+            :city        => "Irving",
+            :state       => "TX",
+            :postal_code => "75039",
+            :country     => "USA"
+          }
+        end
+
+        let(:options) do
+          { :address => address }
+        end
+
+        it "validates the address" do
+          expect{ fedex.validate_address(options) }.to_not raise_error
+        end
+      end
+
+    end
+  end
+end

data/spec/lib/fedex_ship/delete_spec.rb

@@ -0,0 +1,26 @@
+require 'spec_helper'
+
+module FedexShip
+  describe Shipment do
+    let (:fedex) { Shipment.new(fedex_credentials) }
+    context "#delete" do
+      context "delete shipment with tracking number", :vcr do
+        let(:options) do
+          { :tracking_number => '794608797150' }
+        end
+        it "deletes a shipment" do
+          expect{ fedex.delete(options) }.to_not raise_error
+        end
+      end
+      context "raise an error when the tracking number is invalid", :vcr do
+        let(:options) do
+          { :tracking_number => '111111111' }
+        end
+
+        it "raises an error" do
+          expect {fedex.delete(options) }.to raise_error(FedexShip::RateError, 'Invalid tracking number')
+        end
+      end
+    end
+  end
+end

data/spec/lib/fedex_ship/document_spec.rb

@@ -0,0 +1,177 @@
+require 'spec_helper'
+require 'tmpdir'
+
+module FedexShip
+  describe Document do
+    let(:fedex) { Shipment.new(fedex_credentials) }
+    let(:shipper) do
+      { :name => "Sender", :company => "Company", :phone_number => "555-555-5555", :address => "King Street", :city => "Ashbourne", :postal_code => "DE6 1EA", :country_code => "GB" }
+    end
+    let(:recipient) do
+      { :name => "Recipient", :company => "Company", :phone_number => "555-555-5555", :address => "Main Street", :city => "Frankin Park", :state => "IL", :postal_code => "60131", :country_code => "US", :residential => true }
+    end
+    let(:packages) do
+      [
+        {
+          :weight => { :units => "LB", :value => 2 },
+          :dimensions => { :length => 10, :width => 5, :height => 4, :units => "IN" }
+        }
+      ]
+    end
+    let(:shipping_options) do
+      { :packaging_type => "YOUR_PACKAGING", :drop_off_type => "REGULAR_PICKUP" }
+    end
+    let(:customs) do
+      {
+        :duties_payment => {
+          :payment_type => 'SENDER',
+          :payor => {
+            :responsible_party => {
+              :account_number => fedex_credentials[:account_number],
+              :contact => {
+                :person_name => 'Mr. Test',
+                :phone_number => '12345678'
+              }
+            }
+          }
+        },
+        :document_content => 'NON_DOCUMENTS',
+        :customs_value => {
+          :currency => 'UKL', # UK Pounds Sterling
+          :amount => 155.79
+        },
+        :commercial_invoice => {
+          :terms_of_sale => 'DDU'
+        },
+        :commodities => [
+          {
+            :number_of_pieces => 1,
+            :description => 'Pink Toy',
+            :country_of_manufacture => 'GB',
+            :weight => {
+              :units => 'LB',
+              :value => 2
+            },
+            :quantity => 1,
+            :quantity_units => 'EA',
+            :unit_price => {
+              :currency => 'UKL',
+              :amount => 155.79
+            },
+            :customs_value => {
+              :currency => 'UKL', # UK Pounds Sterling
+              :amount => 155.79
+            }
+          }
+        ]
+      }
+    end
+    let(:document) do
+      {
+        :shipping_document_types => 'COMMERCIAL_INVOICE',
+        :commercial_invoice_detail => {
+          :format => {
+            :image_type => 'PDF',
+            :stock_type => 'PAPER_LETTER'
+          }
+        }
+      }
+    end
+
+    let(:filenames) {
+      require 'tmpdir'
+      {
+        :label => File.join(Dir.tmpdir, "label#{rand(15000)}.pdf"),
+        :commercial_invoice => File.join(Dir.tmpdir, "invoice#{rand(15000)}.pdf")
+      }
+    }
+
+    let(:options) do
+      {
+        :shipper => shipper,
+        :recipient => recipient,
+        :packages => packages,
+        :service_type => "INTERNATIONAL_PRIORITY",
+        :shipping_details => shipping_options,
+        :customs_clearance_detail => customs,
+        :shipping_document => document,
+        :filenames => filenames
+      }
+    end
+
+    describe 'document service', :vcr do
+
+      context 'with document specification' do
+
+        before do
+          @document = fedex.document(options)
+        end
+
+        it "saves a label to file" do
+          expect(File).to exist(filenames[:label])
+        end
+
+        it "saves invoice to file" do
+          expect(File).to exist(filenames[:commercial_invoice])
+        end
+
+        it "returns tracking number" do
+          expect(@document).to respond_to('tracking_number')
+        end
+
+        it "exposes complete response" do
+          expect(@document).to respond_to('response_details')
+        end
+
+        it "exposes the filenames" do
+          expect(@document).to respond_to('filenames')
+        end
+
+      end
+
+      context 'without document specification' do
+
+        before do
+          @document = fedex.document(
+            options.reject{|k| k == :shipping_document}
+          )
+        end
+
+        it "saves a label to file" do
+          expect(File).to exist(filenames[:label])
+        end
+
+        it "has no others files" do
+          expect(File).not_to exist(filenames[:commercial_invoice])
+        end
+
+      end
+
+      context 'filename missed' do
+        context 'for label' do
+          before do
+            filenames.delete(:label)
+            @document = fedex.document(options)
+          end
+
+          it "saves invoice to file" do
+            expect(File).to exist(filenames[:commercial_invoice])
+          end
+        end
+
+        context 'for invoice' do
+          before do
+            filenames.delete(:commercial_invoice)
+            @document = fedex.document(options)
+          end
+
+          it "saves label to file" do
+            expect(File).to exist(filenames[:label])
+          end
+        end
+      end
+
+    end
+
+  end
+end