easypost 3.5.1 → 5.2.0

data/lib/easypost/hooks.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module EasyPost::Hooks
+  def self.subscribe(type, name, block)
+    subscribers[type][name] = block
+
+    name
+  end
+
+  def self.unsubscribe(type, name)
+    subscribers[type].delete(name)
+  end
+
+  def self.unsubscribe_all(type)
+    subscribers.delete(type)
+  end
+
+  def self.notify(type, context)
+    subscribers[type].each_value { |subscriber| subscriber.call(context) }
+  end
+
+  def self.any_subscribers?(type)
+    !subscribers[type].empty?
+  end
+
+  def self.subscribers
+    @subscribers ||= Hash.new { |hash, key| hash[key] = {} }
+  end
+
+  private_class_method :subscribers
+end
+
+require_relative 'hooks/request_context'
+require_relative 'hooks/response_context'

data/lib/easypost/http_client.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+class EasyPost::HttpClient
+  def initialize(base_url, config, custom_client_exec = nil)
+    @base_url = base_url
+    @config = config
+    @custom_client_exec = custom_client_exec
+  end
+
+  # Execute an HTTP request to the API.
+  def request(
+    method,
+    path,
+    headers = nil,
+    body = nil,
+    api_version = EasyPost::InternalUtilities::Constants::API_VERSION
+  )
+    # Remove leading slash from path.
+    path = path[1..] if path[0] == '/'
+
+    uri = URI.parse("#{@base_url}/#{api_version}/#{path}")
+    headers = @config[:headers].merge(headers || {})
+    serialized_body = JSON.dump(EasyPost::InternalUtilities.objects_to_ids(body)) if body
+    open_timeout = @config[:open_timeout]
+    read_timeout = @config[:read_timeout]
+    request_timestamp = Time.now
+    request_uuid = SecureRandom.uuid
+
+    if EasyPost::Hooks.any_subscribers?(:request)
+      request_context = EasyPost::Hooks::RequestContext.new(
+        method: method,
+        path: uri.to_s,
+        headers: headers,
+        request_body: body,
+        request_timestamp: request_timestamp,
+        request_uuid: request_uuid,
+      )
+      EasyPost::Hooks.notify(:request, request_context)
+    end
+
+    # Execute the request, return the response.
+
+    response = if @custom_client_exec
+                 @custom_client_exec.call(method, uri, headers, open_timeout, read_timeout, serialized_body)
+               else
+                 default_request_execute(method, uri, headers, open_timeout, read_timeout, serialized_body)
+               end
+    response_timestamp = Time.now
+
+    if EasyPost::Hooks.any_subscribers?(:response)
+      response_context = {
+        http_status: nil,
+        method: method,
+        path: uri.to_s,
+        headers: nil,
+        response_body: nil,
+        request_timestamp: request_timestamp,
+        response_timestamp: response_timestamp,
+        client_response_object: response,
+        request_uuid: request_uuid,
+      }
+
+      # If using a custom HTTP client, the user will have to infer these from the raw
+      # client_response_object attribute
+      if response.is_a?(Net::HTTPResponse)
+        response_body = begin
+          JSON.parse(response.body)
+        rescue JSON::ParseError
+          response.body
+        end
+        response_context.merge!(
+          {
+            http_status: response.code.to_i,
+            headers: response.each_header.to_h,
+            response_body: response_body,
+          },
+        )
+      end
+
+      EasyPost::Hooks.notify(:response, EasyPost::Hooks::ResponseContext.new(**response_context))
+    end
+
+    response
+  end
+
+  def default_request_execute(method, uri, headers, open_timeout, read_timeout, body = nil)
+    # Create the request, set the headers and body if necessary.
+    request = Net::HTTP.const_get(method.capitalize).new(uri)
+    headers.each { |k, v| request[k] = v }
+    request.body = body if body
+
+    begin
+      # Attempt to make the request and return the response.
+      Net::HTTP.start(
+        uri.host,
+        uri.port,
+        use_ssl: true,
+        read_timeout: read_timeout,
+        open_timeout: open_timeout,
+      ) do |http|
+        http.request(request)
+      end
+    rescue Net::ReadTimeout, Net::OpenTimeout, Errno::EHOSTUNREACH => e
+      # Raise a timeout error if the request times out.
+      raise EasyPost::Errors::TimeoutError.new(e.message)
+    rescue OpenSSL::SSL::SSLError => e
+      # Raise an SSL error if the request fails due to an SSL error.
+      raise EasyPost::Errors::SslError.new(e.message)
+    rescue StandardError => e
+      # Raise an unknown HTTP error if anything else causes the request to fail to complete
+      # (this is different from processing 4xx/5xx errors from the API)
+      raise EasyPost::Errors::UnknownApiError.new(e.message)
+    end
+  end
+end

data/lib/easypost/internal_utilities.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module EasyPost::InternalUtilities
+  # Convert a string to snake case
+  def self.to_snake_case(str)
+    str.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+       .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+       .downcase
+  end
+
+  # 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
+      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..].each do |key|
+      result += "[#{key}]"
+    end
+
+    result
+  end
+
+  # Converts an object to an object ID.
+  def self.objects_to_ids(obj)
+    case obj
+    when EasyPost::Models::EasyPostObject
+      { 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
+
+  # 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
+end
+
+require_relative 'utilities/json'
+require_relative 'utilities/system'
+require_relative 'utilities/static_mapper'
+require_relative 'utilities/constants'

data/lib/easypost/models/address.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Address objects are used to represent people, places, and organizations in a number of contexts.
+class EasyPost::Models::Address < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/api_key.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# An ApiKey object that has your EasyPost API.
+class EasyPost::Models::ApiKey < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/base.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'json'
+
+# The base class for all JSON objects in the library.
+class EasyPost::Models::Object
+  def initialize(data)
+    @values = data
+    add_properties(data)
+  end
+
+  # Convert to a string.
+  def to_s(*_args)
+    JSON.dump(@values)
+  end
+
+  # Convert object to hash
+  def to_hash
+    JSON.parse(JSON.dump(@values))
+  end
+
+  # Get element of an array.
+  def [](key)
+    @values[key.to_s]
+  end
+
+  # Set the element of an array.
+  def []=(key, value)
+    send(:"#{key}=", value)
+  end
+
+  private
+
+  def add_properties(values)
+    values.each do |key, _|
+      define_singleton_method(key) { handle_value(@values[key]) } # getter
+      define_singleton_method("#{key}=") { |v| @values[key] = handle_value(v) } # setter
+    end
+  end
+
+  def handle_value(val)
+    case val
+    when Hash
+      type = EasyPost::InternalUtilities::StaticMapper::BY_TYPE[val['object']] if val['object']
+      prefix = EasyPost::InternalUtilities::StaticMapper::BY_PREFIX[val['id'].split('_').first] if val['id']
+      cls = type || prefix || EasyPost::Models::EasyPostObject
+      cls.new(val)
+    when Array
+      val.map { |item| handle_value(item) }
+    else
+      val
+    end
+  end
+end
+
+# The base class for all API objects in the library that have an ID (plus optional timestamps).
+class EasyPost::Models::EasyPostObject < EasyPost::Models::Object
+end

data/lib/easypost/models/batch.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# The Batch object allows you to perform operations on multiple Shipments at once.
+class EasyPost::Models::Batch < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/brand.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# The Brand object allows you to customize the publicly-accessible html page that shows tracking details for every EasyPost tracker.
+class EasyPost::Models::Brand < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/carbon_offset.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# The CarbonOffset object is a summary of carbon offset data for a given rate, including grams, price and currency
+class EasyPost::Models::CarbonOffset < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/carrier_account.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# A CarrierAccount encapsulates your credentials with the carrier.
+class EasyPost::Models::CarrierAccount < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/carrier_type.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# A CarrierType details the valid fields for a CarrierAccount.
+class EasyPost::Models::CarrierType < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/customs_info.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# CustomsInfo objects contain CustomsItem objects and all necessary information for the generation of customs forms required for international shipping.
+class EasyPost::Models::CustomsInfo < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/customs_item.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# A CustomsItem object describes goods for international shipment and should be created then included in a CustomsInfo object.
+class EasyPost::Models::CustomsItem < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/end_shipper.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# EndShipper objects are fully-qualified Address objects that require all parameters and get verified upon creation.
+class EasyPost::Models::EndShipper < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# EasyPost Error object.
+class EasyPost::Models::Error
+  attr_reader :code, :field, :message
+
+  # Initialize a new EasyPost Error
+  def initialize(code, field = nil, message = nil)
+    @code = code
+    @field = field
+    @message = message
+  end
+
+  # Create an EasyPost Error from an API error response.
+  def self.from_api_error_response(data)
+    code = data['code']
+    field = data['field'] || nil
+    message = data['message'] || nil
+    EasyPost::Models::Error.new(code, field, message)
+  end
+end

data/lib/easypost/models/event.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Webhook Events are triggered by changes in objects you've created via the API.
+class EasyPost::Models::Event < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/insurance.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# An Insurance object represents insurance for packages purchased both via the EasyPost API as well
+# as shipments purchased through third parties and later registered with EasyPost.
+class EasyPost::Models::Insurance < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/order.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# The Order object represents a collection of packages and can be used for Multi-Piece Shipments.
+class EasyPost::Models::Order < EasyPost::Models::EasyPostObject
+  # Get the lowest rate of an Order (can exclude by having `'!'` as the first element of your optional filter lists).
+  def lowest_rate(carriers = [], services = [])
+    EasyPost::Util.get_lowest_object_rate(self, carriers, services)
+  end
+end

data/lib/easypost/models/parcel.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Parcel objects represent the physical container being shipped.
+class EasyPost::Models::Parcel < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/payload.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Webhook Event Payloads are triggered by changes in objects you've created via the API.
+class EasyPost::Models::Payload < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/payment_method.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# PaymentMethod objects represent a payment method of a user.
+class EasyPost::Models::PaymentMethod < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/pickup.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# The Pickup object allows you to schedule a pickup from your carrier from your customer's residence or place of business.
+class EasyPost::Models::Pickup < EasyPost::Models::EasyPostObject
+  # Get the lowest rate of a Pickup (can exclude by having `'!'` as the first element of your optional filter lists).
+  def lowest_rate(carriers = [], services = [])
+    EasyPost::Util.get_lowest_object_rate(self, carriers, services, 'pickup_rates')
+  end
+end

data/lib/easypost/models/pickup_rate.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# A PickupRate is the rate available for a Pickup.
+class EasyPost::Models::PickupRate < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/postage_label.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# PostageLabel is the object containing details about the shipping label.
+class EasyPost::Models::PostageLabel < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/rate.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# A Rate object contains all the details about the rate of a Shipment.
+class EasyPost::Models::Rate < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/referral.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# ReferralCustomer objects are User objects created from a Partner user.
+class EasyPost::Models::Referral < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/refund.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# The Refund object contains details about the Refund of a Shipment.
+class EasyPost::Models::Refund < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/report.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# A Report contains a csv that is a log of all the objects created within a certain time frame.
+class EasyPost::Models::Report < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/scan_form.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# A ScanForm can be created to speed up and simplify the carrier pickup process. The ScanForm is one document that can
+# be scanned to mark all included tracking codes as "Accepted for Shipment" by the carrier.
+class EasyPost::Models::ScanForm < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/shipment.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# The workhorse of the EasyPost API, a Shipment is made up of a "to" and "from" Address, the Parcel
+# being shipped, and any customs forms required for international deliveries.
+class EasyPost::Models::Shipment < EasyPost::Models::EasyPostObject
+  # Get the lowest rate of a Shipment (can exclude by having `'!'` as the first element of your optional filter lists).
+  def lowest_rate(carriers = [], services = [])
+    EasyPost::Util.get_lowest_object_rate(self, carriers, services)
+  end
+end

data/lib/easypost/models/tax_identifier.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# TaxIdentifiers are identifying numbers or IDs that are used to charge a specific party when
+# dealing with the importing or exporting of good across international borders.
+class EasyPost::Models::TaxIdentifier < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/tracker.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# A Tracker object contains all of the tracking information for a package.
+class EasyPost::Models::Tracker < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/user.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# The User object can be used to manage your own account and to create child accounts.
+class EasyPost::Models::User < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/webhook.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Each Webhook contains the url which EasyPost will notify whenever an object in our system updates. Several types of objects are processed
+# asynchronously in the EasyPost system, so whenever an object updates, an Event is sent via HTTP POST to each configured webhook URL.
+class EasyPost::Models::Webhook < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module EasyPost::Models
+end
+
+require_relative 'models/base' # Must be imported first before the rest of child models
+require_relative 'models/address'
+require_relative 'models/api_key'
+require_relative 'models/batch'
+require_relative 'models/brand'
+require_relative 'models/carbon_offset'
+require_relative 'models/carrier_account'
+require_relative 'models/carrier_type'
+require_relative 'models/customs_info'
+require_relative 'models/customs_item'
+require_relative 'models/end_shipper'
+require_relative 'models/error'
+require_relative 'models/event'
+require_relative 'models/insurance'
+require_relative 'models/order'
+require_relative 'models/parcel'
+require_relative 'models/payload'
+require_relative 'models/payment_method'
+require_relative 'models/pickup_rate'
+require_relative 'models/pickup'
+require_relative 'models/postage_label'
+require_relative 'models/rate'
+require_relative 'models/referral'
+require_relative 'models/refund'
+require_relative 'models/report'
+require_relative 'models/scan_form'
+require_relative 'models/shipment'
+require_relative 'models/tax_identifier'
+require_relative 'models/tracker'
+require_relative 'models/user'
+require_relative 'models/webhook'

data/lib/easypost/services/address.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class EasyPost::Services::Address < EasyPost::Services::Service
+  MODEL_CLASS = EasyPost::Models::Address
+
+  # Create an address.
+  def create(params = {})
+    address = params.reject { |k, _| [:verify, :verify_strict].include?(k) }
+
+    wrapped_params = { address: address }
+
+    if params[:verify]
+      wrapped_params[:verify] = params[:verify]
+    end
+
+    if params[:verify_strict]
+      wrapped_params[:verify_strict] = params[:verify_strict]
+    end
+
+    @client.make_request(:post, 'addresses', MODEL_CLASS, params)
+  end
+
+  # Create and verify an Address in one call.
+  def create_and_verify(params = {})
+    wrapped_params = {}
+    wrapped_params[:address] = params
+
+    @client.make_request(:post, 'addresses/create_and_verify', MODEL_CLASS, wrapped_params).address
+  end
+
+  # Verify an Address.
+  def verify(id)
+    @client.make_request(:get, "addresses/#{id}/verify", MODEL_CLASS).address
+  end
+
+  # Retrieve an Address.
+  def retrieve(id)
+    @client.make_request(:get, "addresses/#{id}", MODEL_CLASS)
+  end
+
+  # Retrieve all Addresses.
+  def all(filters = {})
+    @client.make_request(:get, 'addresses', MODEL_CLASS, filters)
+  end
+
+  # Get the next page of addresses.
+  def get_next_page(collection, page_size = nil)
+    get_next_page_helper(collection, collection.addresses, 'addresses', MODEL_CLASS, page_size)
+  end
+end

data/lib/easypost/services/api_key.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class EasyPost::Services::ApiKey < EasyPost::Services::Service
+  # Retrieve all api keys.
+  def all
+    @client.make_request(:get, 'api_keys', EasyPost::Models::ApiKey)
+  end
+end

data/lib/easypost/services/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# The base class for all services in the library.
+class EasyPost::Services::Service
+  def initialize(client)
+    @client = client
+  end
+
+  protected
+
+  # Get next page of an object collection
+  def get_next_page_helper(collection, current_page_items, endpoint, cls, page_size = nil)
+    has_more = collection.has_more || false
+    unless !has_more || current_page_items.nil? || current_page_items.empty?
+      params = {}
+      params[:before_id] = current_page_items.last.id
+      unless page_size.nil?
+        params[:page_size] = page_size
+      end
+
+      @client.make_request(:get, endpoint, cls, params)
+    end
+
+    # issue with getting the next page
+    raise EasyPost::Errors::EndOfPaginationError.new
+  end
+end