Class: FriendlyShipping::Services::USPSShip

Inherits:
Object
  • Object
show all
Includes:
Dry::Monads::Result::Mixin
Defined in:
lib/friendly_shipping/services/usps_ship.rb,
lib/friendly_shipping/services/usps_ship/api_error.rb,
lib/friendly_shipping/services/usps_ship/access_token.rb,
lib/friendly_shipping/services/usps_ship/timing_options.rb,
lib/friendly_shipping/services/usps_ship/shipping_methods.rb,
lib/friendly_shipping/services/usps_ship/machinable_package.rb,
lib/friendly_shipping/services/usps_ship/rate_estimate_options.rb,
lib/friendly_shipping/services/usps_ship/parse_timings_response.rb,
lib/friendly_shipping/services/usps_ship/parse_rate_estimates_response.rb,
lib/friendly_shipping/services/usps_ship/rate_estimate_package_options.rb,
lib/friendly_shipping/services/usps_ship/serialize_rate_estimates_request.rb

Defined Under Namespace

Classes: AccessToken, ApiError, MachinablePackage, ParseRateEstimatesResponse, ParseTimingsResponse, RateEstimateOptions, RateEstimatePackageOptions, SerializeRateEstimatesRequest

Constant Summary collapse

CARRIER =

The USPS carrier

FriendlyShipping::Carrier.new(
  id: 'usps',
  name: 'United States Postal Service',
  code: 'usps',
  shipping_methods: SHIPPING_METHODS
)
BASE_URL =

The base URL for USPS Ship requests

'https://api.usps.com'
RESOURCES =

The USPS Ship API endpoints

{
  token: 'oauth2/v3/token',
  rates: 'prices/v3/base-rates/search',
  timings: 'service-standards/v3/estimates'
}.freeze
TimingOptions = 
RateEstimateOptions
SHIPPING_METHODS = 
[
  ["BOUND_PRINTED_MATTER", "Bound Printed Matter"],
  ["FIRST-CLASS_PACKAGE_RETURN_SERVICE", "First-Class Package Return Service"],
  ["FIRST-CLASS_PACKAGE_SERVICE", "First-Class Package Service"],
  ["GROUND_RETURN_SERVICE", "Ground Return Service"],
  ["LIBRARY_MAIL", "Library Mail"],
  ["MEDIA_MAIL", "Media Mail"],
  ["PARCEL_SELECT", "Parcel Select"],
  ["PARCEL_SELECT_LIGHTWEIGHT", "Parcel Select Lightweight"],
  ["PRIORITY_MAIL", "Priority Mail"],
  ["PRIORITY_MAIL_EXPRESS", "Priority Mail Express"],
  ["PRIORITY_MAIL_EXPRESS_RETURN_SERVICE", "Priority Mail Express Return Service"],
  ["PRIORITY_MAIL_RETURN_SERVICE", "Priority Mail Return Service"],
  ["USPS_CONNECT_LOCAL", "USPS Connect Local"],
  ["USPS_CONNECT_MAIL", "USPS Connect Mail"],
  ["USPS_CONNECT_NEXT_DAY", "USPS Connect Next Day"],
  ["USPS_CONNECT_REGIONAL", "USPS Connect Regional"],
  ["USPS_CONNECT_SAME_DAY", "USPS Connect Same Day"],
  ["USPS_GROUND_ADVANTAGE", "USPS Ground Advantage"],
  ["USPS_GROUND_ADVANTAGE_RETURN_SERVICE", "USPS Ground Advantage Return Service"],
  ["USPS_RETAIL_GROUND", "USPS Retail Ground"]
].map do |code, name|
  FriendlyShipping::ShippingMethod.new(
    origin_countries: [Carmen::Country.coded("US")],
    name: name,
    service_code: code,
    domestic: true,
    international: false
  )
end.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(access_token:, test: true, client: nil) ⇒ USPSShip 



55
56
57
58
59
60
 
# File 'lib/friendly_shipping/services/usps_ship.rb', line 55

def initialize(access_token:, test: true, client: nil)
  @access_token = access_token
  @test = test
  error_handler = ApiErrorHandler.new(api_error_class: USPSShip::ApiError)
  @client = client || HttpClient.new(error_handler: error_handler)
end

Instance Attribute Details

#access_token ⇒ AccessToken (readonly) 



26
27
28
 
# File 'lib/friendly_shipping/services/usps_ship.rb', line 26

def access_token
  @access_token
end

#client ⇒ HttpClient (readonly) 



32
33
34
 
# File 'lib/friendly_shipping/services/usps_ship.rb', line 32

def client
  @client
end

#test ⇒ Boolean (readonly) 



29
30
31
 
# File 'lib/friendly_shipping/services/usps_ship.rb', line 29

def test
  @test
end

Instance Method Details

#carriers ⇒ Array<Carrier> 



63
64
65
 
# File 'lib/friendly_shipping/services/usps_ship.rb', line 63

def carriers
  Success([CARRIER])
end

#create_access_token(client_id:, client_secret:, grant_type: "client_credentials", debug: false) ⇒ ApiResult<AccessToken>

Creates an access token that can be used for future API requests.

See Also:



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
 
# File 'lib/friendly_shipping/services/usps_ship.rb', line 75

def create_access_token(
  client_id:,
  client_secret:,
  grant_type: "client_credentials",
  debug: false
)
  request = FriendlyShipping::Request.new(
    url: "#{BASE_URL}/#{RESOURCES[:token]}",
    http_method: "POST",
    body: "client_id=#{client_id}&" \
          "client_secret=#{client_secret}&" \
          "grant_type=#{grant_type}",
    headers: {
      Content_Type: "application/x-www-form-urlencoded",
      Accept: "application/json"
    },
    debug: debug
  )
  client.post(request).fmap do |response|
    hash = JSON.parse(response.body)
    FriendlyShipping::ApiResult.new(
      AccessToken.new(
        token_type: hash['token_type'],
        expires_in: hash['expires_in'],
        raw_token: hash['access_token']
      ),
      original_request: request,
      original_response: response
    )
  end
end

#rate_estimates(shipment, options:, debug: false) ⇒ Result<ApiResult<Array<Rate>>>

Get rate estimates. NOTE: Since USPS Ship does not support returning multiple rates at the same time, we have to make multiple API calls for shipments with more than one package and sum the results.

See Also:



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
 
# File 'lib/friendly_shipping/services/usps_ship.rb', line 117

def rate_estimates(shipment, options:, debug: false)
  api_results = shipment.packages.map do |package|
    yield begin
      rate_request = SerializeRateEstimatesRequest.call(shipment: shipment, package: package, options: options)
      request = build_request(api: :rates, payload: rate_request, debug: debug)

      client.post(request).bind do |response|
        ParseRateEstimatesResponse.call(response: response, request: request)
      end
    end
  end

  rates = api_results.flat_map(&:data)
  amounts = rates.each_with_object({}) do |rate, result|
    rate.amounts.each do |name, amount|
      result[name] ||= 0
      result[name] += amount
    end
  end

  Success(
    ApiResult.new(
      [
        FriendlyShipping::Rate.new(
          amounts: amounts,
          shipping_method: rates.first.shipping_method,
          data: rates.first.data
        )
      ],
      original_request: api_results.first.original_request,
      original_response: api_results.first.original_response
    )
  )
end

#timings(shipment, options:, debug: false) ⇒ Result<ApiResult<Array<Timing>>>

Get timing estimates.

See Also:



158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/friendly_shipping/services/usps_ship.rb', line 158

def timings(shipment, options:, debug: false)
  request = FriendlyShipping::Request.new(
    url: "#{BASE_URL}/#{RESOURCES[:timings]}?" \
         "originZIPCode=#{shipment.origin.zip}&" \
         "destinationZIPCode=#{shipment.destination.zip}&" \
         "mailClass=#{options.shipping_method.service_code}&" \
         "acceptanceDate=#{options.mailing_date.strftime('%Y-%m-%d')}",
    http_method: "GET",
    debug: debug,
    headers: {
      Accept: "application/json",
      Authorization: "Bearer #{access_token.raw_token}"
    }
  )

  client.get(request).bind do |response|
    ParseTimingsResponse.call(response: response, request: request)
  end
end