easypost 4.13.0 → 5.0.0

data/lib/easypost/{payload.rb → models/payload.rb}

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 # Webhook Event Payloads are triggered by changes in objects you've created via the API.
-class EasyPost::Payload < EasyPost::Resource
+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/{pickup_rate.rb → models/pickup_rate.rb}

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

data/lib/easypost/{postage_label.rb → models/postage_label.rb}

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 # PostageLabel is the object containing details about the shipping label.
-class EasyPost::PostageLabel < EasyPost::Resource
+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/{tax_identifier.rb → models/tax_identifier.rb}

@@ -2,5 +2,5 @@
 
 # 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::TaxIdentifier < EasyPost::Resource
+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,35 @@
+# 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/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

data/lib/easypost/services/batch.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+class EasyPost::Services::Batch < EasyPost::Services::Service
+  MODEL_CLASS = EasyPost::Models::Batch
+
+  # Create a Batch.
+  def create(params = {})
+    wrapped_params = { batch: params }
+
+    @client.make_request(:post, 'batches', MODEL_CLASS, wrapped_params)
+  end
+
+  # Create and buy a batch in one call.
+  def create_and_buy(params = {})
+    wrapped_params = { batch: params }
+
+    @client.make_request(:post, 'batches/create_and_buy', MODEL_CLASS, wrapped_params)
+  end
+
+  def all(params = {})
+    @client.make_request(:get, 'batches', EasyPost::Models::ApiKey, params)
+  end
+
+  # Retrieve a Batch
+  def retrieve(id)
+    @client.make_request(:get, "batches/#{id}", MODEL_CLASS)
+  end
+
+  # Buy a Batch.
+  def buy(id, params = {})
+    @client.make_request(:post, "batches/#{id}/buy", MODEL_CLASS, params)
+  end
+
+  # Convert the label format of a Batch.
+  def label(id, params = {})
+    @client.make_request(:post, "batches/#{id}/label", MODEL_CLASS, params)
+  end
+
+  # Remove Shipments from a Batch.
+  def remove_shipments(id, params = {})
+    @client.make_request(:post, "batches/#{id}/remove_shipments", MODEL_CLASS, params)
+  end
+
+  # Add Shipments to a Batch.
+  def add_shipments(id, params = {})
+    @client.make_request(:post, "batches/#{id}/add_shipments", MODEL_CLASS, params)
+  end
+
+  # Create a ScanForm for a Batch.
+  def create_scan_form(id, params = {})
+    @client.make_request(:post, "batches/#{id}/scan_form", MODEL_CLASS, params)
+  end
+end

data/lib/easypost/services/beta_rate.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class EasyPost::Services::BetaRate < EasyPost::Services::Service
+  # Retrieve a list of stateless rates.
+  def retrieve_stateless_rates(params = {})
+    wrapped_params = {
+      shipment: params,
+    }
+
+    @client.make_request(:post, 'rates', EasyPost::Models::Rate, wrapped_params, 'beta').rates
+  end
+end

data/lib/easypost/services/beta_referral_customer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+class EasyPost::Services::BetaReferralCustomer < EasyPost::Services::Service
+  # Add a Stripe payment method to a ReferralCustomer Customer. This function requires the ReferralCustomer Customer's API key.
+  def add_payment_method(stripe_customer_id, payment_method_reference, priority = 'primary')
+    wrapped_params = {
+      payment_method: {
+        stripe_customer_id: stripe_customer_id,
+        payment_method_reference: payment_method_reference,
+        priority: priority.downcase,
+      },
+    }
+    @client.make_request(
+      :post,
+      'referral_customers/payment_method',
+      EasyPost::Models::EasyPostObject,
+      wrapped_params,
+      'beta',
+    )
+  end
+
+  # Refund a ReferralCustomer Customer's wallet by a specified amount. Refund will be issued to the user's original payment method.
+  # This function requires the ReferralCustomer Customer's API key.
+  def refund_by_amount(amount)
+    params = {
+      refund_amount: amount,
+    }
+    @client.make_request(:post, 'referral_customers/refunds', EasyPost::Models::EasyPostObject, params, 'beta')
+    # noinspection RubyMismatchedReturnType
+  end
+
+  # Refund a ReferralCustomer Customer's wallet for a specified payment log entry. Refund will be issued to the user's original payment method.
+  # This function requires the ReferralCustomer Customer's API key.
+  def refund_by_payment_log(payment_log_id)
+    params = {
+      payment_log_id: payment_log_id,
+    }
+    @client.make_request(:post, 'referral_customers/refunds', EasyPost::Models::EasyPostObject, params, 'beta')
+  end
+end

data/lib/easypost/services/billing.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'easypost/constants'
+
+class EasyPost::Services::Billing < EasyPost::Services::Service
+  # Get payment method info (type of the payment method and ID of the payment method)
+  def self.get_payment_method_info(priority)
+    payment_methods = EasyPost::Services::Billing.retrieve_payment_methods
+    payment_method_map = {
+      'primary' => 'primary_payment_method',
+      'secondary' => 'secondary_payment_method',
+    }
+
+    payment_method_to_use = payment_method_map[priority]
+
+    error_string = EasyPost::Constants::INVALID_PAYMENT_METHOD
+    suggestion = "Please use a valid payment method: #{payment_method_map.keys.join(', ')}"
+    if payment_methods[payment_method_to_use].nil?
+      raise EasyPost::Errors::InvalidParameterError.new(
+        error_string,
+        suggestion,
+      )
+    end
+
+    payment_method_id = payment_methods[payment_method_to_use]['id']
+
+    unless payment_method_id.nil?
+      if payment_method_id.start_with?('card_')
+        endpoint = '/v2/credit_cards'
+      elsif payment_method_id.start_with?('bank_')
+        endpoint = '/v2/bank_accounts'
+      else
+        raise EasyPost::Errors::InvalidObjectError.new(error_string)
+      end
+    end
+
+    [endpoint, payment_method_id]
+  end
+
+  # Fund your EasyPost wallet by charging your primary or secondary card on file.
+  def fund_wallet(amount, priority = 'primary')
+    payment_info = EasyPost::Services::Billing.get_payment_method_info(priority.downcase)
+    endpoint = payment_info[0]
+    payment_id = payment_info[1]
+
+    wrapped_params = { amount: amount }
+    @client.make_request(:post, "#{endpoint}/#{payment_id}/charges", EasyPost::Models::EasyPostObject, wrapped_params)
+
+    # Return true if succeeds, an error will be thrown if it fails
+    true
+  end
+
+  # Delete a payment method.
+  def delete_payment_method(priority)
+    payment_info = EasyPost::Services::Billing.get_payment_method_info(priority.downcase)
+    endpoint = payment_info[0]
+    payment_id = payment_info[1]
+
+    @client.make_request(:delete, "#{endpoint}/#{payment_id}")
+
+    # Return true if succeeds, an error will be thrown if it fails
+    true
+  end
+
+  # Retrieve all payment methods.
+  def retrieve_payment_methods
+    response = @client.make_request(:get, '/v2/payment_methods')
+
+    if response['id'].nil?
+      raise EasyPost::Errors::InvalidObjectError.new(EasyPost::Constants::NO_PAYMENT_METHODS)
+    end
+
+    response
+  end
+end

data/lib/easypost/services/carrier_account.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+class EasyPost::Services::CarrierAccount < EasyPost::Services::Service
+  CUSTOM_WORKFLOW_CARRIER_TYPES = %w[UpsAccount FedexAccount].freeze
+  MODEL_CLASS = EasyPost::Models::CarrierAccount
+
+  # Create a carrier account
+  def create(params = {})
+    wrapped_params = { carrier_account: params }
+
+    # For UPS and FedEx the endpoint is different
+    create_url = if CUSTOM_WORKFLOW_CARRIER_TYPES.include?(params[:type])
+                   'carrier_accounts/register'
+                 else
+                   'carrier_accounts'
+                 end
+
+    @client.make_request(:post, create_url, MODEL_CLASS, wrapped_params)
+  end
+
+  # Retrieve a carrier account
+  def retrieve(id)
+    @client.make_request(:get, "carrier_accounts/#{id}", MODEL_CLASS)
+  end
+
+  # Retrieve all carrier accounts
+  def all(params = {})
+    @client.make_request(:get, 'carrier_accounts', MODEL_CLASS, params)
+  end
+
+  # Update a carrier account
+  def update(id, params = {})
+    wrapped_params = { carrier_account: params }
+    @client.make_request(:put, "carrier_accounts/#{id}", MODEL_CLASS, wrapped_params)
+  end
+
+  # Delete a carrier account
+  def delete(id)
+    @client.make_request(:delete, "carrier_accounts/#{id}")
+
+    # Return true if succeeds, an error will be thrown if it fails
+    true
+  end
+end

data/lib/easypost/services/carrier_metadata.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class EasyPost::Services::CarrierMetadata < EasyPost::Services::Service
+  # Retrieve metadata for carrier(s).
+  def retrieve(carriers = [], types = [])
+    path = '/metadata/carriers?'
+
+    params = {}
+
+    if carriers.length.positive?
+      params[:carriers] = carriers.join(',')
+    end
+
+    if types.length.positive?
+      params[:types] = types.join(',')
+    end
+
+    path += URI.encode_www_form(params)
+
+    @client.make_request(:get, path, EasyPost::Models::EasyPostObject, params).carriers
+  end
+end

data/lib/easypost/services/customs_info.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class EasyPost::Services::CustomsInfo < EasyPost::Services::Service
+  MODEL_CLASS = EasyPost::Models::CustomsInfo
+
+  # Create a CustomsInfo object
+  def create(params)
+    @client.make_request(:post, 'customs_infos', MODEL_CLASS, params)
+  end
+
+  # Retrieve a CustomsInfo object
+  def retrieve(id)
+    @client.make_request(:get, "customs_infos/#{id}", MODEL_CLASS)
+  end
+end

data/lib/easypost/services/customs_item.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class EasyPost::Services::CustomsItem < EasyPost::Services::Service
+  MODEL_CLASS = EasyPost::Models::CustomsItem
+
+  # Create a CustomsItem object
+  def create(params)
+    @client.make_request(:post, 'customs_items', MODEL_CLASS, params)
+  end
+
+  # Retrieve a CustomsItem object
+  def retrieve(id)
+    @client.make_request(:get, "customs_items/#{id}", MODEL_CLASS)
+  end
+end

data/lib/easypost/services/end_shipper.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class EasyPost::Services::EndShipper < EasyPost::Services::Service
+  MODEL_CLASS = EasyPost::Models::EndShipper
+
+  # Create an EndShipper object.
+  def create(params = {})
+    wrapped_params = { address: params }
+
+    @client.make_request(:post, 'end_shippers', MODEL_CLASS, wrapped_params)
+  end
+
+  # Retrieve an EndShipper object.
+  def retrieve(id)
+    @client.make_request(:get, "end_shippers/#{id}", MODEL_CLASS)
+  end
+
+  # Retrieve all EndShipper objects.
+  def all(params = {})
+    @client.make_request(:get, 'end_shippers', MODEL_CLASS, params)
+  end
+
+  # Updates an EndShipper object. This requires all parameters to be set.
+  def update(id, params)
+    wrapped_params = { address: params }
+
+    @client.make_request(:put, "end_shippers/#{id}", MODEL_CLASS, wrapped_params)
+  end
+
+  # TODO: Add support for getting the next page of end shippers when the API supports it.
+end

data/lib/easypost/services/event.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'json'
+
+class EasyPost::Services::Event < EasyPost::Services::Service
+  MODEL_CLASS = EasyPost::Models::Event
+
+  # Retrieve an Event object
+  def retrieve(id)
+    @client.make_request(:get, "events/#{id}", MODEL_CLASS)
+  end
+
+  # Retrieve all Event objects
+  def all(params = {})
+    @client.make_request(:get, 'events', MODEL_CLASS, params)
+  end
+
+  # Retrieve all payloads for an event.
+  def retrieve_all_payloads(event_id)
+    @client.make_request(:get, "events/#{event_id}/payloads", EasyPost::Models::Payload)
+  end
+
+  # Retrieve a specific payload for an event.
+  def retrieve_payload(event_id, payload_id)
+    @client.make_request(:get, "events/#{event_id}/payloads/#{payload_id}", EasyPost::Models::Payload)
+  end
+
+  # Get the next page of events.
+  def get_next_page(collection, page_size = nil)
+    get_next_page_helper(collection, collection.events, 'events', MODEL_CLASS, page_size)
+  end
+end

data/lib/easypost/services/insurance.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class EasyPost::Services::Insurance < EasyPost::Services::Service
+  MODEL_CLASS = EasyPost::Models::Insurance
+
+  # Create an Insurance object
+  def create(params = {})
+    wrapped_params = { insurance: params }
+    @client.make_request(:post, 'insurances', MODEL_CLASS, wrapped_params)
+  end
+
+  # Retrieve an Insurance object
+  def retrieve(id)
+    @client.make_request(:get, "insurances/#{id}", MODEL_CLASS)
+  end
+
+  # Retrieve all Insurance objects
+  def all(params = {})
+    @client.make_request(:get, 'insurances', MODEL_CLASS, params)
+  end
+
+  # Get the next page of insurances.
+  def get_next_page(collection, page_size = nil)
+    get_next_page_helper(collection, collection.insurances, 'insurances', MODEL_CLASS, page_size)
+  end
+end

data/lib/easypost/services/order.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class EasyPost::Services::Order < EasyPost::Services::Service
+  MODEL_CLASS = EasyPost::Models::Order
+
+  # Create an Order object
+  def create(params = {})
+    wrapped_params = { order: params }
+    @client.make_request(:post, 'orders', MODEL_CLASS, wrapped_params)
+  end
+
+  # Retrieve an Order object
+  def retrieve(id)
+    @client.make_request(:get, "orders/#{id}", MODEL_CLASS)
+  end
+
+  # Retrieve new rates for an Order object
+  def get_rates(id, params = {})
+    @client.make_request(:get, "orders/#{id}/rates", MODEL_CLASS, params)
+  end
+
+  # Buy an Order object
+  def buy(id, params = {})
+    if params.instance_of?(EasyPost::Models::Rate)
+      params = { carrier: params[:carrier], service: params[:service] }
+    end
+
+    @client.make_request(:post, "orders/#{id}/buy", MODEL_CLASS, params)
+  end
+end

data/lib/easypost/services/parcel.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class EasyPost::Services::Parcel < EasyPost::Services::Service
+  MODEL_CLASS = EasyPost::Models::Parcel
+
+  # Create a Parcel object
+  def create(params = {})
+    wrapped_params = { parcel: params }
+    @client.make_request(:post, 'parcels', MODEL_CLASS, wrapped_params)
+  end
+
+  # Retrieve a Parcel object
+  def retrieve(id)
+    @client.make_request(:get, "parcels/#{id}", MODEL_CLASS)
+  end
+end