Class: ActiveShipping::Carrier
- Inherits:
-
Object
- Object
- ActiveShipping::Carrier
- Includes:
- ActiveUtils::PostsData, ActiveUtils::RequiresParameters, Quantified
- Defined in:
- lib/active_shipping/carrier.rb
Overview
Carrier is abstract the base class for all supported carriers.
To implement support for a carrier, you should subclass this class and implement all the methods the carrier supports.
Direct Known Subclasses
BenchmarkCarrier, BogusCarrier, CanadaPost, CanadaPostPWS, Correios, FedEx, Kunaki, NewZealandPost, Shipwire, Stamps, UPS, USPS
Instance Attribute Summary collapse
-
#last_request ⇒ Object
The last request performed against the carrier's API.
-
#test_mode ⇒ Boolean
(also: #test_mode?)
Whether to interact with the carrier's sandbox environment.
Class Method Summary collapse
-
.default_location ⇒ ActiveShipping::Location
protected
The default location to use for #valid_credentials?.
Instance Method Summary collapse
-
#create_shipment(origin, destination, packages, options = {}) ⇒ ActiveShipping::ShipmentResponse
Registers a new shipment with the carrier, to get a tracking number and potentially shipping labels.
-
#find_rates(origin, destination, packages, options = {}) ⇒ ActiveShipping::RateResponse
Asks the carrier for rate estimates for a given shipment.
-
#find_tracking_info(tracking_number, options = {}) ⇒ ActiveShipping::TrackingResponse
Retrieves tracking information for a previous shipment.
-
#initialize(options = {}) ⇒ Carrier
constructor
Credentials should be in options hash under keys :login, :password and/or :key.
-
#maximum_weight ⇒ Quantified::Mass
The maximum weight the carrier will accept.
-
#requirements ⇒ Array<Symbol>
protected
Returns the keys that are required to be passed to the options hash.
-
#save_request(r)
protected
Use after building the request to save for later inspection.
-
#timestamp_from_business_day(days) ⇒ DateTime
protected
Calculates a timestamp that corresponds a given number if business days in the future.
-
#valid_credentials? ⇒ Boolean
Validate credentials with a call to the API.
Constructor Details
#initialize(options = {}) ⇒ Carrier
Credentials should be in options hash under keys :login, :password and/or :key.
30 31 32 33 34 35 |
# File 'lib/active_shipping/carrier.rb', line 30 def initialize( = {}) requirements.each { |key| requires!(, key) } @options = @last_request = nil @test_mode = @options[:test] end |
Instance Attribute Details
#last_request ⇒ Object
The last request performed against the carrier's API.
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 |
# File 'lib/active_shipping/carrier.rb', line 19 class Carrier include Quantified attr_reader :last_request attr_accessor :test_mode alias_method :test_mode?, :test_mode # Credentials should be in options hash under keys :login, :password and/or :key. # @param options [Hash] The details needed to connect to the carrier's API. # @option options [Boolean] :test Set this to true to connect to the carrier's # sandbox environment instead of the production environment. def initialize( = {}) requirements.each { |key| requires!(, key) } @options = @last_request = nil @test_mode = @options[:test] end # Asks the carrier for rate estimates for a given shipment. # # @note Override with whatever you need to get the rates from the carrier. # # @param origin [ActiveShipping::Location] Where the shipment will originate from. # @param destination [ActiveShipping::Location] Where the package will go. # @param packages [Array<ActiveShipping::Package>] The list of packages that will # be in the shipment. # @param options [Hash] Carrier-specific parameters. # @return [ActiveShipping::RateResponse] The response from the carrier, which # includes 0 or more rate estimates for different shipping products def find_rates(origin, destination, packages, = {}) raise NotImplementedError, "#find_rates is not supported by #{self.class.name}." end # Registers a new shipment with the carrier, to get a tracking number and # potentially shipping labels # # @note Override with whatever you need to register a shipment, and obtain # shipping labels if supported by the carrier. # # @param origin [ActiveShipping::Location] Where the shipment will originate from. # @param destination [ActiveShipping::Location] Where the package will go. # @param packages [Array<ActiveShipping::Package>] The list of packages that will # be in the shipment. # @param options [Hash] Carrier-specific parameters. # @return [ActiveShipping::ShipmentResponse] The response from the carrier. This # response should include a shipment identifier or tracking_number if successful, # and potentially shipping labels. def create_shipment(origin, destination, packages, = {}) raise NotImplementedError, "#create_shipment is not supported by #{self.class.name}." end # Retrieves tracking information for a previous shipment # # @note Override with whatever you need to get a shipping label # # @param tracking_number [String] The unique identifier of the shipment to track. # @param options [Hash] Carrier-specific parameters. # @return [ActiveShipping::TrackingResponse] The response from the carrier. This # response should a list of shipment tracking events if successful. def find_tracking_info(tracking_number, = {}) raise NotImplementedError, "#find_tracking_info is not supported by #{self.class.name}." end # Validate credentials with a call to the API. # # By default this just does a `find_rates` call with the orgin and destination both as # the carrier's default_location. Override to provide alternate functionality, such as # checking for `test_mode` to use test servers, etc. # # @return [Boolean] Should return `true` if the provided credentials proved to work, # `false` otherswise. def valid_credentials? location = self.class.default_location find_rates(location, location, Package.new(100, [5, 15, 30]), :test => test_mode) rescue ActiveShipping::ResponseError false else true end # The maximum weight the carrier will accept. # @return [Quantified::Mass] def maximum_weight Mass.new(150, :pounds) end protected include ActiveUtils::RequiresParameters include ActiveUtils::PostsData # Returns the keys that are required to be passed to the options hash # @note Override to return required keys in options hash for initialize method. # @return [Array<Symbol>] def requirements [] end # The default location to use for {#valid_credentials?}. # @note Override for non-U.S.-based carriers. # @return [ActiveShipping::Location] def self.default_location Location.new( :country => 'US', :state => 'CA', :city => 'Beverly Hills', :address1 => '455 N. Rexford Dr.', :address2 => '3rd Floor', :zip => '90210', :phone => '1-310-285-1013', :fax => '1-310-275-8159') end # Use after building the request to save for later inspection. # @return [void] def save_request(r) @last_request = r end # Calculates a timestamp that corresponds a given number if business days in the future # # @param days [Integer] The number of business days from now. # @return [DateTime] A timestamp, the provided number of business days in the future. def (days) return unless days date = DateTime.now.utc days.times do begin date = date + 1 end while [0, 6].include?(date.wday) end date end end |
#test_mode ⇒ Boolean Also known as: test_mode?
Whether to interact with the carrier's sandbox environment.
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 |
# File 'lib/active_shipping/carrier.rb', line 19 class Carrier include Quantified attr_reader :last_request attr_accessor :test_mode alias_method :test_mode?, :test_mode # Credentials should be in options hash under keys :login, :password and/or :key. # @param options [Hash] The details needed to connect to the carrier's API. # @option options [Boolean] :test Set this to true to connect to the carrier's # sandbox environment instead of the production environment. def initialize( = {}) requirements.each { |key| requires!(, key) } @options = @last_request = nil @test_mode = @options[:test] end # Asks the carrier for rate estimates for a given shipment. # # @note Override with whatever you need to get the rates from the carrier. # # @param origin [ActiveShipping::Location] Where the shipment will originate from. # @param destination [ActiveShipping::Location] Where the package will go. # @param packages [Array<ActiveShipping::Package>] The list of packages that will # be in the shipment. # @param options [Hash] Carrier-specific parameters. # @return [ActiveShipping::RateResponse] The response from the carrier, which # includes 0 or more rate estimates for different shipping products def find_rates(origin, destination, packages, = {}) raise NotImplementedError, "#find_rates is not supported by #{self.class.name}." end # Registers a new shipment with the carrier, to get a tracking number and # potentially shipping labels # # @note Override with whatever you need to register a shipment, and obtain # shipping labels if supported by the carrier. # # @param origin [ActiveShipping::Location] Where the shipment will originate from. # @param destination [ActiveShipping::Location] Where the package will go. # @param packages [Array<ActiveShipping::Package>] The list of packages that will # be in the shipment. # @param options [Hash] Carrier-specific parameters. # @return [ActiveShipping::ShipmentResponse] The response from the carrier. This # response should include a shipment identifier or tracking_number if successful, # and potentially shipping labels. def create_shipment(origin, destination, packages, = {}) raise NotImplementedError, "#create_shipment is not supported by #{self.class.name}." end # Retrieves tracking information for a previous shipment # # @note Override with whatever you need to get a shipping label # # @param tracking_number [String] The unique identifier of the shipment to track. # @param options [Hash] Carrier-specific parameters. # @return [ActiveShipping::TrackingResponse] The response from the carrier. This # response should a list of shipment tracking events if successful. def find_tracking_info(tracking_number, = {}) raise NotImplementedError, "#find_tracking_info is not supported by #{self.class.name}." end # Validate credentials with a call to the API. # # By default this just does a `find_rates` call with the orgin and destination both as # the carrier's default_location. Override to provide alternate functionality, such as # checking for `test_mode` to use test servers, etc. # # @return [Boolean] Should return `true` if the provided credentials proved to work, # `false` otherswise. def valid_credentials? location = self.class.default_location find_rates(location, location, Package.new(100, [5, 15, 30]), :test => test_mode) rescue ActiveShipping::ResponseError false else true end # The maximum weight the carrier will accept. # @return [Quantified::Mass] def maximum_weight Mass.new(150, :pounds) end protected include ActiveUtils::RequiresParameters include ActiveUtils::PostsData # Returns the keys that are required to be passed to the options hash # @note Override to return required keys in options hash for initialize method. # @return [Array<Symbol>] def requirements [] end # The default location to use for {#valid_credentials?}. # @note Override for non-U.S.-based carriers. # @return [ActiveShipping::Location] def self.default_location Location.new( :country => 'US', :state => 'CA', :city => 'Beverly Hills', :address1 => '455 N. Rexford Dr.', :address2 => '3rd Floor', :zip => '90210', :phone => '1-310-285-1013', :fax => '1-310-275-8159') end # Use after building the request to save for later inspection. # @return [void] def save_request(r) @last_request = r end # Calculates a timestamp that corresponds a given number if business days in the future # # @param days [Integer] The number of business days from now. # @return [DateTime] A timestamp, the provided number of business days in the future. def (days) return unless days date = DateTime.now.utc days.times do begin date = date + 1 end while [0, 6].include?(date.wday) end date end end |
Class Method Details
.default_location ⇒ ActiveShipping::Location (protected)
Override for non-U.S.-based carriers.
The default location to use for #valid_credentials?.
120 121 122 123 124 125 126 127 128 129 |
# File 'lib/active_shipping/carrier.rb', line 120 def self.default_location Location.new( :country => 'US', :state => 'CA', :city => 'Beverly Hills', :address1 => '455 N. Rexford Dr.', :address2 => '3rd Floor', :zip => '90210', :phone => '1-310-285-1013', :fax => '1-310-275-8159') end |
Instance Method Details
#create_shipment(origin, destination, packages, options = {}) ⇒ ActiveShipping::ShipmentResponse
Override with whatever you need to register a shipment, and obtain shipping labels if supported by the carrier.
Registers a new shipment with the carrier, to get a tracking number and potentially shipping labels
66 67 68 |
# File 'lib/active_shipping/carrier.rb', line 66 def create_shipment(origin, destination, packages, = {}) raise NotImplementedError, "#create_shipment is not supported by #{self.class.name}." end |
#find_rates(origin, destination, packages, options = {}) ⇒ ActiveShipping::RateResponse
Override with whatever you need to get the rates from the carrier.
Asks the carrier for rate estimates for a given shipment.
48 49 50 |
# File 'lib/active_shipping/carrier.rb', line 48 def find_rates(origin, destination, packages, = {}) raise NotImplementedError, "#find_rates is not supported by #{self.class.name}." end |
#find_tracking_info(tracking_number, options = {}) ⇒ ActiveShipping::TrackingResponse
Override with whatever you need to get a shipping label
Retrieves tracking information for a previous shipment
78 79 80 |
# File 'lib/active_shipping/carrier.rb', line 78 def find_tracking_info(tracking_number, = {}) raise NotImplementedError, "#find_tracking_info is not supported by #{self.class.name}." end |
#maximum_weight ⇒ Quantified::Mass
The maximum weight the carrier will accept.
101 102 103 |
# File 'lib/active_shipping/carrier.rb', line 101 def maximum_weight Mass.new(150, :pounds) end |
#requirements ⇒ Array<Symbol> (protected)
Override to return required keys in options hash for initialize method.
Returns the keys that are required to be passed to the options hash
113 114 115 |
# File 'lib/active_shipping/carrier.rb', line 113 def requirements [] end |
#save_request(r) (protected)
This method returns an undefined value.
Use after building the request to save for later inspection.
133 134 135 |
# File 'lib/active_shipping/carrier.rb', line 133 def save_request(r) @last_request = r end |
#timestamp_from_business_day(days) ⇒ DateTime (protected)
Calculates a timestamp that corresponds a given number if business days in the future
141 142 143 144 145 146 147 148 149 150 |
# File 'lib/active_shipping/carrier.rb', line 141 def (days) return unless days date = DateTime.now.utc days.times do begin date = date + 1 end while [0, 6].include?(date.wday) end date end |
#valid_credentials? ⇒ Boolean
Validate credentials with a call to the API.
By default this just does a find_rates
call with the orgin and destination both as
the carrier's default_location. Override to provide alternate functionality, such as
checking for test_mode
to use test servers, etc.
90 91 92 93 94 95 96 97 |
# File 'lib/active_shipping/carrier.rb', line 90 def valid_credentials? location = self.class.default_location find_rates(location, location, Package.new(100, [5, 15, 30]), :test => test_mode) rescue ActiveShipping::ResponseError false else true end |