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_city_state_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, ParseCityStateResponse, 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',
  city_state: 'addresses/v3/city-state'
}.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

Returns a new instance of USPSShip.

Parameters:

  • access_token (AccessToken) —

    the access token

  • test (Boolean) (defaults to: true) —

    whether to use the test API version

  • client (HttpClient) (defaults to: nil) —

    optional HTTP client to use for requests



42
43
44
45
46
47
 
# File 'lib/friendly_shipping/services/usps_ship.rb', line 42

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)

Returns the access token.

Returns:



12
13
14
 
# File 'lib/friendly_shipping/services/usps_ship.rb', line 12

def access_token
  @access_token
end

#client ⇒ HttpClient (readonly)

Returns the HTTP client.

Returns:



18
19
20
 
# File 'lib/friendly_shipping/services/usps_ship.rb', line 18

def client
  @client
end

#test ⇒ Boolean (readonly)

Returns whether to use the test API version.

Returns:

  • (Boolean) —

    whether to use the test API version



15
16
17
 
# File 'lib/friendly_shipping/services/usps_ship.rb', line 15

def test
  @test
end

Instance Method Details

#carriers ⇒ Array<Carrier>

Returns:



50
51
52
 
# File 'lib/friendly_shipping/services/usps_ship.rb', line 50

def carriers
  Success([CARRIER])
end

#city_state(location, debug: false) ⇒ Result<ApiResult<Array<Timing>>>, Result<ApiResult<Physical::Location>> Also known as: city_state_lookup

Get city and state for given ZIP code.

Parameters:

  • location (Physical::Location) —

    the location with ZIP code we want to complete

Returns:

  • (Result<ApiResult<Array<Timing>>>) —

    the Timings wrapped in an ApiResult object

  • (Result<ApiResult<Physical::Location>>) —

    The response data from USPS encoded in a Physical::Location object. Country, City and ZIP code will be set, everything else nil.

See Also:



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/friendly_shipping/services/usps_ship.rb', line 172

def city_state(location, debug: false)
  request = FriendlyShipping::Request.new(
    url: "#{BASE_URL}/#{RESOURCES[:city_state]}?ZIPCode=#{location.zip}",
    http_method: "GET",
    debug: debug,
    headers: {
      Accept: "application/json",
      Authorization: "Bearer #{access_token.raw_token}"
    }
  )

  client.get(request).bind do |response|
    ParseCityStateResponse.call(response: response, request: request)
  end
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.

Parameters:

  • client_id (String) —

    the Client ID of your application from the OAuth Client dialog

  • client_secret (String) —

    the secret you created in the OAuth Client Secrets section of the OAuth Client dialog

  • grant_type (String) (defaults to: "client_credentials") —

    defaults to "client_credentials" to indicate you wish to obtain a token representing your confidential client application

  • debug (Boolean) (defaults to: false) —

    whether to append debug information to the API result

Returns:

See Also:



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

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.

Parameters:

  • shipment (Physical::Shipment) —

    the shipment for which we want to get rates

  • options (RateEstimateOptions) —

    options for obtaining rates for this shipment

  • debug (Boolean) (defaults to: false) —

    whether to append debug information to the API result

Returns:

See Also:



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

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.

Parameters:

  • shipment (Physical::Shipment) —

    the shipment for which we want to get timings

  • options (TimingOptions) —

    options for the timing estimate call

Returns:

See Also:



145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/friendly_shipping/services/usps_ship.rb', line 145

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