easypost 4.8.1 → 5.1.0

data/lib/easypost/services/shipment.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'set'
+
+class EasyPost::Services::Shipment < EasyPost::Services::Service
+  MODEL_CLASS = EasyPost::Models::Shipment
+
+  # Create a Shipment.
+  def create(params = {}, with_carbon_offset = false)
+    wrapped_params = {
+      shipment: params,
+      carbon_offset: with_carbon_offset,
+    }
+
+    @client.make_request(:post, 'shipments', MODEL_CLASS, wrapped_params)
+  end
+
+  # Retrieve a Shipment.
+  def retrieve(id)
+    @client.make_request(:get, "shipments/#{id}", MODEL_CLASS)
+  end
+
+  # Retrieve a list of Shipments
+  def all(params = {})
+    response = @client.make_request(:get, 'shipments', MODEL_CLASS, params)
+    response.define_singleton_method(:purchased) { params[:purchased] }
+    response.define_singleton_method(:include_children) { params[:include_children] }
+    response
+  end
+
+  # Get the next page of shipments.
+  def get_next_page(collection, page_size = nil)
+    get_next_page_helper(collection, collection.shipments, 'shipments', MODEL_CLASS, page_size)
+  end
+
+  # Regenerate the rates of a Shipment.
+  def regenerate_rates(id, with_carbon_offset = false)
+    params = { carbon_offset: with_carbon_offset }
+
+    @client.make_request(:post, "shipments/#{id}/rerate", MODEL_CLASS, params)
+  end
+
+  # Get the SmartRates of a Shipment.
+  def get_smart_rates(id)
+    @client.make_request(:get, "shipments/#{id}/smartrate", MODEL_CLASS).result || []
+  end
+
+  # Buy a Shipment.
+  def buy(id, params = {}, with_carbon_offset = false, end_shipper_id = nil)
+    if params.instance_of?(EasyPost::Models::Rate)
+      params = { rate: params.clone }
+    end
+
+    params[:carbon_offset] = params[:with_carbon_offset] || with_carbon_offset
+    params.delete(:with_carbon_offset)
+
+    params[:end_shipper_id] = end_shipper_id if end_shipper_id
+
+    @client.make_request(:post, "shipments/#{id}/buy", MODEL_CLASS, params)
+  end
+
+  # Insure a Shipment.
+  def insure(id, params = {})
+    params = { amount: params } if params.is_a?(Integer) || params.is_a?(Float)
+
+    @client.make_request(:post, "shipments/#{id}/insure", MODEL_CLASS, params)
+  end
+
+  # Refund a Shipment.
+  def refund(id, params = {})
+    @client.make_request(:post, "shipments/#{id}/refund", MODEL_CLASS, params)
+  end
+
+  # Convert the label format of a Shipment.
+  def label(id, params = {})
+    params = { file_format: params } if params.is_a?(String)
+
+    @client.make_request(:get, "shipments/#{id}/label", MODEL_CLASS, params)
+  end
+
+  # Get the lowest SmartRate of a Shipment.
+  def lowest_smart_rate(id, delivery_days, delivery_accuracy)
+    smart_rates = get_smart_rates(id)
+    EasyPost::Util.get_lowest_smart_rate(smart_rates, delivery_days, delivery_accuracy)
+  end
+
+  # Generate a form for a Shipment.
+  def generate_form(id, form_type, form_options = {})
+    params = {}
+    params[:type] = form_type
+    merged_params = params.merge(form_options)
+    wrapped_params = {
+      form: merged_params,
+    }
+
+    @client.make_request(:post, "shipments/#{id}/forms", MODEL_CLASS, wrapped_params)
+  end
+
+  # Retrieves the estimated delivery date of each Rate via SmartRate.
+  def retrieve_estimated_delivery_date(id, planned_ship_date)
+    url = "shipments/#{id}/smartrate/delivery_date"
+    params = { planned_ship_date: planned_ship_date }
+
+    @client.make_request(:get, url, MODEL_CLASS, params).rates
+  end
+end

data/lib/easypost/services/tracker.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class EasyPost::Services::Tracker < EasyPost::Services::Service
+  MODEL_CLASS = EasyPost::Models::Tracker
+
+  # Create a Tracker
+  def create(params = {})
+    wrapped_params = { tracker: params }
+
+    @client.make_request(:post, 'trackers', MODEL_CLASS, wrapped_params)
+  end
+
+  # Retrieve a Tracker
+  def retrieve(id)
+    @client.make_request(:get, "trackers/#{id}", MODEL_CLASS)
+  end
+
+  # Retrieve a list of Trackers
+  def all(params)
+    response = @client.make_request(:get, 'trackers', MODEL_CLASS, params)
+    response.define_singleton_method(:tracking_code) { params[:tracking_code] }
+    response.define_singleton_method(:carrier) { params[:carrier] }
+    response
+  end
+
+  # Create multiple Tracker objects in bulk.
+  def create_list(params = {})
+    wrapped_params = { 'trackers' => params }
+
+    @client.make_request(:post, 'trackers/create_list', MODEL_CLASS, wrapped_params)
+    true # This endpoint does not return a response so we return true here instead
+  end
+
+  # Get the next page of trackers.
+  def get_next_page(collection, page_size = nil)
+    get_next_page_helper(collection, collection.trackers, 'trackers', MODEL_CLASS, page_size)
+  end
+end

data/lib/easypost/services/user.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+class EasyPost::Services::User < EasyPost::Services::Service
+  MODEL_CLASS = EasyPost::Models::User
+
+  # Create a child User.
+  def create(params = {})
+    @client.make_request(:post, 'users', MODEL_CLASS, params)
+  end
+
+  # Retrieve a user
+  def retrieve(id)
+    @client.make_request(:get, "users/#{id}", MODEL_CLASS)
+  end
+
+  # Retrieve the authenticated User.
+  def retrieve_me
+    @client.make_request(:get, 'users', MODEL_CLASS)
+  end
+
+  # Update a User
+  def update(id, params = {})
+    @client.make_request(:put, "users/#{id}", MODEL_CLASS, params)
+  end
+
+  # Delete a User
+  def delete(id)
+    @client.make_request(:delete, "users/#{id}")
+
+    # Return true if succeeds, an error will be thrown if it fails
+    true
+  end
+
+  # Retrieve a list of all ApiKey objects.
+  def all_api_keys
+    @client.make_request(:get, 'api_keys', EasyPost::Models::ApiKey)
+  end
+
+  # Retrieve a list of ApiKey objects (works for the authenticated user or a child user).
+  def api_keys(id)
+    api_keys = all_api_keys
+
+    if api_keys.id == id
+      # This function was called on the authenticated user
+      my_api_keys = api_keys.keys
+    else
+      # This function was called on a child user (authenticated as parent, only return this child user's details).
+      my_api_keys = []
+      api_keys.children.each do |child|
+        if child.id == id
+          my_api_keys = child.keys
+          break
+        end
+      end
+    end
+
+    my_api_keys
+  end
+
+  # Update the Brand of a User.
+  def update_brand(id, params = {})
+    wrapped_params = { brand: params }
+
+    @client.make_request(:get, "users/#{id}/brand", EasyPost::Models::Brand, wrapped_params)
+  end
+end

data/lib/easypost/services/webhook.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class EasyPost::Services::Webhook < EasyPost::Services::Service
+  MODEL_CLASS = EasyPost::Models::Webhook
+
+  # Create a Webhook.
+  def create(params = {})
+    wrapped_params = { webhook: params }
+    @client.make_request(:post, 'webhooks', MODEL_CLASS, wrapped_params)
+  end
+
+  # Retrieve a Webhook
+  def retrieve(id)
+    @client.make_request(:get, "webhooks/#{id}", MODEL_CLASS)
+  end
+
+  # Retrieve a list of Webhooks
+  def all(params = {})
+    @client.make_request(:get, 'webhooks', MODEL_CLASS, params)
+  end
+
+  # Update a Webhook.
+  def update(id, params = {})
+    @client.make_request(:patch, "webhooks/#{id}", MODEL_CLASS, params)
+  end
+
+  # Delete a Webhook.
+  def delete(id)
+    @client.make_request(:delete, "webhooks/#{id}")
+
+    # Return true if succeeds, an error will be thrown if it fails
+    true
+  end
+end

data/lib/easypost/services.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module EasyPost::Services
+end
+
+require_relative 'models'
+require_relative 'services/base' # Must be imported first before the rest of child services
+require_relative 'services/address'
+require_relative 'services/api_key'
+require_relative 'services/batch'
+require_relative 'services/beta_rate'
+require_relative 'services/beta_referral_customer'
+require_relative 'services/billing'
+require_relative 'services/carrier_account'
+require_relative 'services/carrier_metadata'
+require_relative 'services/customs_info'
+require_relative 'services/customs_item'
+require_relative 'services/end_shipper'
+require_relative 'services/event'
+require_relative 'services/insurance'
+require_relative 'services/order'
+require_relative 'services/parcel'
+require_relative 'services/pickup'
+require_relative 'services/rate'
+require_relative 'services/referral_customer'
+require_relative 'services/refund'
+require_relative 'services/report'
+require_relative 'services/scan_form'
+require_relative 'services/shipment'
+require_relative 'services/tracker'
+require_relative 'services/user'
+require_relative 'services/webhook'

data/lib/easypost/util.rb

@@ -1,198 +1,89 @@
 # frozen_string_literal: true
 
-# Internal utilities helpful for this libraries operation.
-module EasyPost::Util
-  attr_accessor :os_name, :os_version, :os_arch
-
-  BY_PREFIX = {
-    'adr' => EasyPost::Address,
-    'batch' => EasyPost::Batch,
-    'brd' => EasyPost::Brand,
-    'ca' => EasyPost::CarrierAccount,
-    'cstinfo' => EasyPost::CustomsInfo,
-    'cstitem' => EasyPost::CustomsItem,
-    'es' => EasyPost::EndShipper,
-    'evt' => EasyPost::Event,
-    'hook' => EasyPost::Webhook,
-    'ins' => EasyPost::Insurance,
-    'order' => EasyPost::Order,
-    'pickup' => EasyPost::Pickup,
-    'pickuprate' => EasyPost::PickupRate,
-    'pl' => EasyPost::PostageLabel,
-    'plrep' => EasyPost::Report,
-    'prcl' => EasyPost::Parcel,
-    'rate' => EasyPost::Rate,
-    'refrep' => EasyPost::Report,
-    'rfnd' => EasyPost::Refund,
-    'sf' => EasyPost::ScanForm,
-    'shp' => EasyPost::Shipment,
-    'shpinvrep' => EasyPost::Report,
-    'shprep' => EasyPost::Report,
-    'trk' => EasyPost::Tracker,
-    'trkrep' => EasyPost::Report,
-    'user' => EasyPost::User,
-  }.freeze
-
-  BY_TYPE = {
-    'Address' => EasyPost::Address,
-    'Batch' => EasyPost::Batch,
-    'Brand' => EasyPost::Brand,
-    'CarbonOffset' => EasyPost::CarbonOffset,
-    'CarrierAccount' => EasyPost::CarrierAccount,
-    'CustomsInfo' => EasyPost::CustomsInfo,
-    'CustomsItem' => EasyPost::CustomsItem,
-    'EndShipper' => EasyPost::EndShipper,
-    'Event' => EasyPost::Event,
-    'Insurance' => EasyPost::Insurance,
-    'Order' => EasyPost::Order,
-    'Parcel' => EasyPost::Parcel,
-    'PaymentLogReport' => EasyPost::Report,
-    'Pickup' => EasyPost::Pickup,
-    'PickupRate' => EasyPost::PickupRate,
-    'PostageLabel' => EasyPost::PostageLabel,
-    'Rate' => EasyPost::Rate,
-    'Referral' => EasyPost::Beta::Referral,
-    'Refund' => EasyPost::Refund,
-    'RefundReport' => EasyPost::Report,
-    'Report' => EasyPost::Report,
-    'ScanForm' => EasyPost::ScanForm,
-    'Shipment' => EasyPost::Shipment,
-    'ShipmentInvoiceReport' => EasyPost::Report,
-    'ShipmentReport' => EasyPost::Report,
-    'TaxIdentifier' => EasyPost::TaxIdentifier,
-    'Tracker' => EasyPost::Tracker,
-    'TrackerReport' => EasyPost::Report,
-    'User' => EasyPost::User,
-    'Webhook' => EasyPost::Webhook,
-  }.freeze
-
-  def self.os_name
-    case RUBY_PLATFORM
-    when /linux/i
-      'Linux'
-    when /darwin/i
-      'Darwin'
-    when /cygwin|mswin|mingw|bccwin|wince|emx/i
-      'Windows'
-    else
-      'Unknown'
-    end
-  end
-
-  def self.os_version
-    Gem::Platform.local.version
-  end
+require 'easypost/constants'
 
-  def self.os_arch
-    Gem::Platform.local.cpu
-  end
+# Client Library helper functions
+module EasyPost::Util
+  # Gets the lowest rate of an EasyPost object such as a Shipment, Order, or Pickup.
+  # You can exclude by having `'!'` as the first element of your optional filter lists
+  def self.get_lowest_object_rate(easypost_object, carriers = [], services = [], rates_key = 'rates')
+    lowest_rate = nil
 
-  # Form-encode a multi-layer dictionary to a one-layer dictionary.
-  def self.form_encode_params(hash, parent_keys = [], parent_dict = {})
-    result = parent_dict or {}
-    keys = parent_keys or []
-
-    hash.each do |key, value|
-      if value.instance_of?(Hash)
-        keys << key
-        result = form_encode_params(value, keys, result)
-      else
-        dict_key = build_dict_key(keys + [key])
-        result[dict_key] = value
+    carriers = EasyPost::InternalUtilities.normalize_string_list(carriers)
+    negative_carriers = []
+    carriers_copy = carriers.clone
+    carriers_copy.each do |carrier|
+      if carrier[0, 1] == '!'
+        negative_carriers << carrier[1..]
+        carriers.delete(carrier)
       end
     end
-    result
-  end
-
-  # Build a dict key from a list of keys.
-  # Example: [code, number] -> code[number]
-  def self.build_dict_key(keys)
-    result = keys[0].to_s
 
-    keys[1..-1].each do |key|
-      result += "[#{key}]"
+    services = EasyPost::InternalUtilities.normalize_string_list(services)
+    negative_services = []
+    services_copy = services.clone
+    services_copy.each do |service|
+      if service[0, 1] == '!'
+        negative_services << service[1..]
+        services.delete(service)
+      end
     end
 
-    result
-  end
-
-  # Converts an object to an object ID.
-  def self.objects_to_ids(obj)
-    case obj
-    when EasyPost::Resource
-      { id: obj.id }
-    when Hash
-      result = {}
-      obj.each { |k, v| result[k] = objects_to_ids(v) unless v.nil? }
-      result
-    when Array
-      obj.map { |v| objects_to_ids(v) }
-    else
-      obj
-    end
-  end
+    easypost_object.send(rates_key).each do |rate|
+      rate_carrier = rate.carrier.downcase
+      if carriers.size.positive? && !carriers.include?(rate_carrier)
+        next
+      end
+      if negative_carriers.size.positive? && negative_carriers.include?(rate_carrier)
+        next
+      end
 
-  # Normalizes a list of strings.
-  def self.normalize_string_list(lst)
-    lst = lst.is_a?(String) ? lst.split(',') : Array(lst)
-    lst.map(&:to_s).map(&:downcase).map(&:strip)
-  end
+      rate_service = rate.service.downcase
+      if services.size.positive? && !services.include?(rate_service)
+        next
+      end
+      if negative_services.size.positive? && negative_services.include?(rate_service)
+        next
+      end
 
-  # Convert data to an EasyPost Object.
-  def self.convert_to_easypost_object(response, api_key, parent = nil, name = nil)
-    case response
-    when Array
-      response.map { |i| convert_to_easypost_object(i, api_key, parent) }
-    when Hash
-      if (cls_name = response[:object])
-        cls = BY_TYPE[cls_name]
-      elsif response[:id]
-        if response[:id].index('_').nil?
-          cls = EasyPost::EasyPostObject
-        elsif (cls_prefix = response[:id][0..response[:id].index('_')])
-          cls = BY_PREFIX[cls_prefix[0..-2]]
-        end
-      elsif response['id']
-        if response['id'].index('_').nil?
-          cls = EasyPost::EasyPostObject
-        elsif (cls_prefix = response['id'][0..response['id'].index('_')])
-          cls = BY_PREFIX[cls_prefix[0..-2]]
-        end
+      if lowest_rate.nil? || rate.rate.to_f < lowest_rate.rate.to_f
+        lowest_rate = rate
       end
+    end
 
-      cls ||= EasyPost::EasyPostObject
-      cls.construct_from(response, api_key, parent, name)
-    else
-      response
+    if lowest_rate.nil?
+      raise EasyPost::Errors::FilteringError.new(EasyPost::Constants::NO_MATCHING_RATES)
     end
+
+    lowest_rate
   end
 
-  # Gets the lowest rate of an EasyPost object such as a Shipment, Order, or Pickup.
+  # Gets the lowest stateless rate.
   # You can exclude by having `'!'` as the first element of your optional filter lists
-  def self.get_lowest_object_rate(easypost_object, carriers = [], services = [], rates_key = 'rates')
+  def self.get_lowest_stateless_rate(stateless_rates, carriers = [], services = [])
     lowest_rate = nil
 
-    carriers = EasyPost::Util.normalize_string_list(carriers)
+    carriers = EasyPost::InternalUtilities.normalize_string_list(carriers)
     negative_carriers = []
     carriers_copy = carriers.clone
     carriers_copy.each do |carrier|
       if carrier[0, 1] == '!'
-        negative_carriers << carrier[1..-1]
+        negative_carriers << carrier[1..]
         carriers.delete(carrier)
       end
     end
 
-    services = EasyPost::Util.normalize_string_list(services)
+    services = EasyPost::InternalUtilities.normalize_string_list(services)
     negative_services = []
     services_copy = services.clone
     services_copy.each do |service|
       if service[0, 1] == '!'
-        negative_services << service[1..-1]
+        negative_services << service[1..]
         services.delete(service)
       end
     end
 
-    easypost_object[rates_key].each do |rate|
+    stateless_rates.each do |rate|
       rate_carrier = rate.carrier.downcase
       if carriers.size.positive? && !carriers.include?(rate_carrier)
         next
@@ -214,8 +105,72 @@ module EasyPost::Util
       end
     end
 
-    raise EasyPost::Error.new('No rates found.') if lowest_rate.nil?
+    if lowest_rate.nil?
+      raise EasyPost::Errors::FilteringError.new(EasyPost::Constants::NO_MATCHING_RATES)
+    end
 
     lowest_rate
   end
+
+  # Converts a raw webhook event into an EasyPost object.
+  def self.receive_event(raw_input)
+    EasyPost::InternalUtilities::Json.convert_json_to_object(JSON.parse(raw_input), EasyPost::Models::EasyPostObject)
+  end
+
+  # Get the lowest SmartRate from a list of SmartRate.
+  def self.get_lowest_smart_rate(smart_rates, delivery_days, delivery_accuracy)
+    valid_delivery_accuracy_values = Set[
+      'percentile_50',
+      'percentile_75',
+      'percentile_85',
+      'percentile_90',
+      'percentile_95',
+      'percentile_97',
+      'percentile_99',
+    ]
+    lowest_smart_rate = nil
+
+    unless valid_delivery_accuracy_values.include?(delivery_accuracy.downcase)
+      raise EasyPost::Errors::InvalidParameterError.new(
+        'delivery_accuracy',
+        "Must be one of: #{valid_delivery_accuracy_values}",
+      )
+    end
+
+    smart_rates.each do |rate|
+      next if rate['time_in_transit'][delivery_accuracy] > delivery_days.to_i
+
+      if lowest_smart_rate.nil? || rate['rate'].to_f < lowest_smart_rate['rate'].to_f
+        lowest_smart_rate = rate
+      end
+    end
+
+    if lowest_smart_rate.nil?
+      raise EasyPost::Errors::FilteringError.new(EasyPost::Constants::NO_MATCHING_RATES)
+    end
+
+    lowest_smart_rate
+  end
+
+  # Validate a webhook by comparing the HMAC signature header sent from EasyPost to your shared secret.
+  # If the signatures do not match, an error will be raised signifying the webhook either did not originate
+  # from EasyPost or the secrets do not match. If the signatures do match, the `event_body` will be returned
+  # as JSON.
+  def self.validate_webhook(event_body, headers, webhook_secret)
+    easypost_hmac_signature = headers['X-Hmac-Signature']
+
+    if easypost_hmac_signature.nil?
+      raise EasyPost::Errors::SignatureVerificationError.new(EasyPost::Constants::WEBHOOK_MISSING_SIGNATURE)
+    end
+
+    encoded_webhook_secret = webhook_secret.unicode_normalize(:nfkd).encode('utf-8')
+
+    expected_signature = OpenSSL::HMAC.hexdigest('sha256', encoded_webhook_secret, event_body)
+    digest = "hmac-sha256-hex=#{expected_signature}"
+    unless digest == easypost_hmac_signature
+      raise EasyPost::Errors::SignatureVerificationError.new(EasyPost::Constants::WEBHOOK_SIGNATURE_MISMATCH)
+    end
+
+    JSON.parse(event_body)
+  end
 end

data/lib/easypost/utilities/constants.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EasyPost::InternalUtilities::Constants
+  API_VERSION = 'v2'
+end

data/lib/easypost/utilities/json.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module EasyPost::InternalUtilities::Json
+  def self.convert_json_to_object(data, cls = EasyPost::Models::EasyPostObject)
+    data = JSON.parse(data) if data.is_a?(String) # Parse JSON to a Hash or Array if it's a string
+    if data.is_a?(Array)
+      # Deserialize array data into an array of objects
+      data.map { |i| convert_json_to_object(i, cls) }
+    elsif data.is_a?(Hash)
+      # Deserialize hash data into a new object instance
+      cls.new(data)
+    else
+      # data is neither a Hash nor Array (but somehow was parsed as JSON? This should never happen)
+      data
+    end
+  rescue JSON::ParserError
+    data # Not JSON, return the original data (used mostly when dealing with final values like strings, booleans, etc.)
+  end
+
+  def self.http_response_is_json?(response)
+    response['Content-Type'] ? response['Content-Type'].start_with?('application/json') : false
+  end
+end