we_ship_client 1.0.0

data/lib/we_ship_client/entities/responses/process_orders.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'we_ship_client/entities/base'
+require 'we_ship_client/entities/responses/order_accepted'
+require 'we_ship_client/entities/responses/rejected_orders'
+
+module WeShipClient
+  module Entities
+    module Responses
+      # The response returned by `Interactors::ProcessOrders`.
+      class ProcessOrders < Base
+        attribute? :ordersHeldInGateway, Types::Strict::Array.of(OrderAccepted).optional
+        attribute? :rejectedorders, RejectedOrders.optional
+      end
+    end
+  end
+end

data/lib/we_ship_client/entities/responses/proof_of_delivery.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'we_ship_client/entities/base'
+
+module WeShipClient
+  module Entities
+    module Responses
+      # The proof of delivery data of a single order.
+      class ProofOfDelivery < Base
+        attribute :additional_information, Types::Strict::String.optional.default(nil)
+        attribute :delivery_date, Types::Strict::String.optional.default(nil)
+        attribute :signature, Types::Strict::String.optional.default(nil)
+        attribute :signer_name, Types::Strict::String.optional.default(nil)
+        attribute :visual, Types::Strict::String.optional.default(nil)
+      end
+    end
+  end
+end

data/lib/we_ship_client/entities/responses/rejected_orders.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'we_ship_client/entities/base'
+require 'we_ship_client/entities/responses/order_rejected'
+
+module WeShipClient
+  module Entities
+    module Responses
+      # Just a container for the rejected orders list.
+      # Note the singular "order" name that may be confusing.
+      class RejectedOrders < Base
+        attribute? :count, Types::Strict::Integer.optional
+        attribute :order, Types::Strict::Array.of(OrderRejected).optional
+      end
+    end
+  end
+end

data/lib/we_ship_client/entities/responses/track_order.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'we_ship_client/entities/base'
+require 'we_ship_client/entities/responses/proof_of_delivery'
+require 'we_ship_client/entities/responses/tracking_item'
+
+module WeShipClient
+  module Entities
+    module Responses
+      # The details of a single order returned by `Interactors::GetTracking`.
+      class TrackOrder < Base
+        attribute :address1, Types::Strict::String
+        attribute :address2, Types::Strict::String.optional
+        attribute :carrier, Types::Strict::String.optional
+        attribute :carrier_tracking_num, Types::Strict::String.optional
+        attribute :city, Types::Strict::String
+        attribute :client_ref1, Types::Strict::String
+        attribute :customer_code, Types::Strict::String
+        attribute :estimated_delivery_date, Types::Strict::String.optional
+        attribute :fgw_order_id, Types::Coercible::Integer.optional
+        attribute :internal_tracking_num, Types::Strict::String.optional
+        attribute :last_tracking_update, Types::Strict::String.optional
+        attribute :name, Types::Strict::String
+        attribute :postal_code, Types::Strict::String
+        attribute? :proof_of_delivery, ProofOfDelivery.optional
+        attribute :state, Types::Strict::String
+        attribute :tracking_items, Types::Strict::Array.of(TrackingItem)
+        attribute :upload_date, Types::Strict::String
+      end
+    end
+  end
+end

data/lib/we_ship_client/entities/responses/track_response.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'we_ship_client/entities/base'
+require 'we_ship_client/entities/responses/track_order'
+
+module WeShipClient
+  module Entities
+    module Responses
+      # The response returned by `Interactors::GetTracking`.
+      class TrackResponse < Base
+        attribute? :page_num, Types::Strict::Integer
+        attribute :results, Types::Strict::Array.of(TrackOrder)
+      end
+    end
+  end
+end

data/lib/we_ship_client/entities/responses/tracking_item.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'we_ship_client/entities/base'
+
+module WeShipClient
+  module Entities
+    module Responses
+      # A single tracking item returned by `Interactors::GetTracking`.
+      class TrackingItem < Base
+        attribute :location, Types::Strict::String.optional
+        attribute :message, Types::Strict::String
+        attribute :status_type, Types::Strict::String
+        attribute :tracking_item_date, Types::Strict::String.optional.default(nil)
+        attribute :tracking_item_id, Types::Coercible::Integer.optional.default(nil)
+      end
+    end
+  end
+end

data/lib/we_ship_client/entities/track_request.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'we_ship_client/entities/base'
+
+module WeShipClient
+  module Entities
+    # The request payload used by `Interactors::GetTracking`.
+    class TrackRequest < Base
+      BATCH_SIZE = 500
+
+      attribute? :order_id, Types::Strict::Array.of(Types::Strict::String)
+      attribute? :client_ref1, Types::Strict::Array.of(Types::Strict::String)
+      attribute? :carrier_tracking_num, Types::Strict::Array.of(Types::Strict::String)
+      attribute? :internal_tracking_num, Types::Strict::Array.of(Types::Strict::String)
+      attribute :customer_code, Types::Strict::Array.of(Types::Strict::String)
+      attribute? :status, Types::Strict::String.enum('M', 'I', 'D', 'R', 'X', 'P', 'N', 'C')
+      attribute :page_num, Types::Strict::Integer.default(0)
+      attribute :num_records, Types::Strict::Integer.default(BATCH_SIZE)
+    end
+  end
+end

data/lib/we_ship_client/entities/types.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'dry-types'
+
+module WeShipClient
+  module Entities
+    module Types
+      begin
+        include Dry.Types()
+      rescue NoMethodError # dry-types < 0.15
+        include Dry::Types.module
+      end
+    end
+  end
+end

data/lib/we_ship_client/entities.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'we_ship_client/entities/base'
+require 'we_ship_client/entities/address'
+require 'we_ship_client/entities/order_item'
+require 'we_ship_client/entities/order_items'
+require 'we_ship_client/entities/order'
+require 'we_ship_client/entities/process_orders_request'
+require 'we_ship_client/entities/track_request'
+require 'we_ship_client/entities/responses/order_accepted'
+require 'we_ship_client/entities/responses/order_rejected'
+require 'we_ship_client/entities/responses/process_orders'
+require 'we_ship_client/entities/responses/proof_of_delivery'
+require 'we_ship_client/entities/responses/rejected_orders'
+require 'we_ship_client/entities/responses/track_order'
+require 'we_ship_client/entities/responses/track_response'
+require 'we_ship_client/entities/responses/tracking_item'

data/lib/we_ship_client/exceptions.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module WeShipClient
+  module Exceptions
+    class BaseError < RuntimeError
+    end
+
+    class AuthenticationError < BaseError
+    end
+
+    class NotFoundError < BaseError
+    end
+
+    class ServerError < BaseError
+    end
+  end
+end

data/lib/we_ship_client/interactors/get_tracking.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'we_ship_client/client'
+require 'we_ship_client/exceptions'
+require 'we_ship_client/entities'
+require 'we_ship_client/transforms/tracking_item'
+
+module WeShipClient
+  module Interactors
+    # Class to interact with the /track API endpoint.
+    class GetTracking
+      ERRONEOUS_EXCEPTION_MSGS = [
+        'RQA Mapping',
+        'OQA Mapping',
+        'SML Mapping',
+        'Out for Delivery'
+      ].freeze
+
+      # @param auth_token [String] A token generated by TokenClient
+      # @param track_request [Entities::TrackRequest] The request payload
+      # @param timeout [Integer,nil] The request timeout
+      def initialize(auth_token:, track_request:, timeout: nil)
+        @auth_token = auth_token
+        @request = track_request
+        @timeout = timeout
+      end
+
+      # Get the tracking response.
+      #
+      # @raise [Exceptions::AuthenticationError] If the status code is 401
+      # @raise [Exceptions::ServerError] If the response is blank
+      # @return [Entities::Responses::TrackResponse] The tracking response
+      def call
+        response = client.http_client.post(
+          "#{client.base_url}/track",
+          data: request.to_hash,
+          headers: { Authorization: "JWT #{auth_token}" }
+        )
+        handle_exception(response) unless response.status == 200
+        json_response = JSON.parse(response.body, symbolize_names: true)
+        handle_exception(response) if json_response[:results].nil?
+        filter_results(json_response)
+        modified_response(response_class.new(json_response))
+      end
+
+      private
+
+      attr_accessor :auth_token, :request, :timeout
+
+      def handle_exception(response)
+        WeShipClient.logger.info(
+          "[WeShipClient::Interactors::GetTracking] [EXCEPTION] #{response}"
+        )
+
+        http_errors = {
+          401 => WeShipClient::Exceptions::AuthenticationError
+        }
+
+        raise http_errors[response.status], response.body if http_errors.key?(response.status)
+
+        raise WeShipClient::Exceptions::ServerError, response.body
+      end
+
+      def response_class
+        WeShipClient::Entities::Responses::TrackResponse
+      end
+
+      def client
+        @client ||= WeShipClient::Client.new(timeout: timeout)
+      end
+
+      def filter_results(response) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        # filters out tracking items with empty message
+        # filters out tracking items with empty tracking_item_date and tracking_item_id
+        response[:results].each do |track_order|
+          next unless track_order[:tracking_items]
+
+          track_order[:tracking_items] = track_order[:tracking_items].select do |item|
+            valid_tracking_item?(item)
+          end
+        end
+      end
+
+      def valid_tracking_item?(item)
+        # either date or id must be present
+        (item[:tracking_item_date].present? || item[:tracking_item_id].present?) &&
+          # message must be present
+          item[:message].present? &&
+          # does not have a erroneous exception message
+          !(item[:status_type] == 'X' && erroneous_exception_msg?(item[:message]))
+      end
+
+      def erroneous_exception_msg?(item_message)
+        ERRONEOUS_EXCEPTION_MSGS.any? do |msg|
+          item_message.downcase.start_with?(msg.downcase)
+        end
+      end
+
+      def modified_response(response)
+        response.results.each do |track_order|
+          track_order&.tracking_items&.map do |item|
+            next if item.tracking_item_date.nil? && item.tracking_item_id.nil?
+
+            tracking_item_transform_class.new.call(
+              tracking_item: item,
+              state: track_order.state
+            )
+          end
+        end
+
+        response
+      end
+
+      def tracking_item_transform_class
+        WeShipClient::Transforms::TrackingItem
+      end
+    end
+  end
+end

data/lib/we_ship_client/interactors/process_orders.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'we_ship_client/client'
+require 'we_ship_client/entities'
+require 'we_ship_client/exceptions'
+
+module WeShipClient
+  module Interactors
+    # Class to interact with the /process_orders API endpoint.
+    class ProcessOrders
+      # @param auth_token [String] A token generated by TokenClient
+      # @param process_orders_request [Entities::ProcessOrdersRequest] The request payload
+      def initialize(auth_token:, process_orders_request:)
+        @auth_token = auth_token
+        @process_orders_request = process_orders_request
+      end
+
+      # Sends orders to be processed.
+      #
+      # @raise [Exceptions::AuthenticationError] If the status code is 401
+      # @raise [Exceptions::ServerError] If the request is not successful
+      # @return [Entities::Responses::ProcessOrders] The response
+      def call
+        json_response = client.http_client.post(
+          "#{client.base_url}/process_orders",
+          data: process_orders_request.to_h,
+          headers: {
+            Authorization: "JWT #{auth_token}"
+          }
+        )
+
+        handle_exception(json_response) unless json_response.status == 200
+        response_hash = JSON.parse(json_response.body, symbolize_names: true)
+        response_class.new(response_hash[:response])
+      end
+
+      private
+
+      attr_accessor :auth_token, :process_orders_request
+
+      def handle_exception(response)
+        WeShipClient.logger.info(
+          "[WeShipClient::Interactors::ProcessOrders] [EXCEPTION] #{response}"
+        )
+
+        case response.status
+        when 401
+          raise WeShipClient::Exceptions::AuthenticationError, response.body
+        else
+          raise WeShipClient::Exceptions::ServerError, response.body
+        end
+      end
+
+      def client
+        @client ||= WeShipClient::Client.new
+      end
+
+      def response_class
+        WeShipClient::Entities::Responses::ProcessOrders
+      end
+    end
+  end
+end

data/lib/we_ship_client/token_client.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'we_ship_client/client'
+require 'we_ship_client/exceptions'
+
+module WeShipClient
+  class TokenClient < Client
+    # @raise [Exceptions::AuthenticationError] If status is 401
+    # @raise [Exceptions::ServerError] If status is not 200
+    # @return [String] The access token
+    def generate_access_token
+      response = http_client.post(
+        "#{base_url}/token",
+        data: {
+          username: ENV['WE_SHIP_USERNAME'],
+          password: ENV['WE_SHIP_PASSWORD']
+        }
+      )
+
+      raise_token_generation_exception(response) unless response.status == 200
+
+      JSON.parse(response.body)['access_token']
+    end
+
+    private
+
+    def raise_token_generation_exception(response)
+      case response.status
+      when 401
+        raise WeShipClient::Exceptions::AuthenticationError, response.body
+      else
+        raise WeShipClient::Exceptions::ServerError, response.body
+      end
+    end
+  end
+end

data/lib/we_ship_client/transforms/tracking_item.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'active_support/time_with_zone'
+
+module WeShipClient
+  module Transforms
+    # A class that modifies/converts/removes some tracking items data to match our needs.
+    # If you want to use your custom logic, create another class and set it on
+    # `Interactors::GetTracking#tracking_item_transform_class`
+    class TrackingItem
+      # Following array of messages mean the status is a delivery exception regardless
+      # of what the actual status_type is received from weship
+      OVERRIDE_DELIVERED = [
+        'Delivered, Signed by 85',
+        'Delivered, Signed by no answer at door',
+        'Delivered, Signed by LOST'
+      ].freeze
+      OVERRIDE_DELIVERY_EXCEPTION = ['48'].freeze
+      OVERRIDE_STATUS_TO_DELIVERY_EXCEPTION = ['No One Avail Sig Required'].freeze
+      OVERRIDE_STATUS_TO_RETURNED = [
+        'Delivered, Signed by RETURN',
+        'Delivered, Signed by 3 att',
+        'Delivered, Signed by RTS'
+      ].freeze
+      OVERRIDE_STATUS_TO_MANIFEST = ['Electronically Transmitted'].freeze
+      DUPLICATE_DELIMITER = '----'
+      DELIVERY_ATTEMPTED_MESSAGE = 'Delivery attempt was made'
+      RETURNED_MESSAGE = 'Return to Sender'
+      UNDELIVERABLE_MESSAGE = 'undeliverable'
+      OUT_FOR_DELIVERY_MESSAGE = 'Out for Delivery'
+
+      ET_STATES = %w[CT DE FL GA IN ME MD MA MI NH NJ NY NC OH PA RI SC VT VA WV].freeze
+      CT_STATES = %w[AL AR IL IA KS KY LA MN MS MO NE ND OK SD TN TX WI].freeze
+      MT_STATES = %w[AZ CO ID MT NM UT WY].freeze
+      PT_STATES = %w[CA NV OR WA].freeze
+
+      def call(tracking_item:, state:) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        if should_override_delivered_to_exception?(tracking_item)
+          tracking_item.status_type.replace('X')
+          tracking_item.message.replace(DELIVERY_ATTEMPTED_MESSAGE)
+        elsif should_override_delivered_to_returned?(tracking_item)
+          tracking_item.status_type.replace('R')
+          tracking_item.message.replace(RETURNED_MESSAGE)
+        elsif should_override_delivery_exception_message?(tracking_item)
+          tracking_item.message.replace(DELIVERY_ATTEMPTED_MESSAGE)
+        elsif should_override_status_to_exception?(tracking_item)
+          tracking_item.status_type.replace('X')
+        elsif should_override_out_for_delivery_status?(tracking_item)
+          tracking_item.status_type.replace('I')
+        elsif should_override_exception_to_manifest?(tracking_item)
+          tracking_item.status_type.replace('M')
+        end
+
+        # if there is a extraneous driver related message text, override to simpler message
+        tracking_item.message.replace('With driver') if should_override_driver_details?(tracking_item)
+        if should_remove_delimeters?(tracking_item)
+          # remove duplicates from message
+          tracking_item.message.replace(tracking_item.message.split(DUPLICATE_DELIMITER)[0])
+        end
+        # weship datetime is local carrier time, so convert it to UTC
+        convert_date_to_utc(tracking_item, state)
+      end
+
+      def should_override_exception_to_manifest?(tracking_item)
+        tracking_item.status_type == 'X' &&
+          OVERRIDE_STATUS_TO_MANIFEST.any? do |message|
+            tracking_item.message.downcase.start_with?(message.downcase)
+          end
+      end
+
+      def should_override_delivered_to_exception?(tracking_item)
+        tracking_item.status_type == 'D' &&
+          [
+            OVERRIDE_DELIVERED.any? { |message| tracking_item.message.downcase.start_with?(message.downcase) },
+            tracking_item.message.downcase.include?(UNDELIVERABLE_MESSAGE.downcase)
+          ].any?
+      end
+
+      def should_override_delivered_to_returned?(tracking_item)
+        tracking_item.status_type == 'D' &&
+          OVERRIDE_STATUS_TO_RETURNED.any? do |message|
+            tracking_item.message.downcase.start_with?(message.downcase)
+          end
+      end
+
+      def should_override_delivery_exception_message?(tracking_item)
+        tracking_item.status_type == 'X' &&
+          OVERRIDE_DELIVERY_EXCEPTION.any? do |message|
+            tracking_item.message.downcase.start_with?(message.downcase)
+          end
+      end
+
+      def should_override_status_to_exception?(tracking_item)
+        OVERRIDE_STATUS_TO_DELIVERY_EXCEPTION.any? do |message|
+          tracking_item.message.downcase.start_with?(message.downcase)
+        end
+      end
+
+      def should_remove_delimeters?(tracking_item)
+        tracking_item.message.index(DUPLICATE_DELIMITER)&.positive?
+      end
+
+      def should_override_out_for_delivery_status?(tracking_item)
+        tracking_item.status_type == 'X' &&
+          tracking_item.message.downcase.include?(OUT_FOR_DELIVERY_MESSAGE.downcase)
+      end
+
+      def should_override_driver_details?(tracking_item)
+        tracking_item.message.downcase.index('driver:')
+      end
+
+      def convert_date_to_utc(tracking_item, state)
+        date = tracking_item.tracking_item_date
+        if date.present?
+          timezone = ActiveSupport::TimeZone.new(us_timezone_from(state))
+          utc_date = timezone.local_to_utc(DateTime.parse(date)).to_s
+          tracking_item.tracking_item_date.replace(utc_date)
+        end
+      end
+
+      def us_timezone_from(state)
+        if ET_STATES.include?(state)
+          'Eastern Time (US & Canada)'
+        elsif CT_STATES.include?(state)
+          'Central Time (US & Canada)'
+        elsif MT_STATES.include?(state)
+          'Mountain Time (US & Canada)'
+        elsif PT_STATES.include?(state)
+          'Pacific Time (US & Canada)'
+        else # default to est
+          'Eastern Time (US & Canada)'
+        end
+      end
+    end
+  end
+end

data/lib/we_ship_client/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module WeShipClient
+  VERSION = '1.0.0'
+end

data/lib/we_ship_client.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'we_ship_client/client'
+require 'we_ship_client/entities'
+require 'we_ship_client/exceptions'
+require 'we_ship_client/token_client'
+require 'we_ship_client/interactors/get_tracking'
+require 'we_ship_client/interactors/process_orders'
+require 'we_ship_client/transforms/tracking_item'
+
+module WeShipClient
+  def self.logger
+    defined?(Rails) ? Rails.logger : Logger.new(STDOUT)
+  end
+end

data/we_ship_client.gemspec

@@ -0,0 +1,33 @@
+require_relative 'lib/we_ship_client/version'
+
+Gem::Specification.new do |spec|
+  spec.required_ruby_version = '>= 2.6'
+  spec.name          = 'we_ship_client'
+  spec.version       = WeShipClient::VERSION
+  spec.authors       = ['Juul Labs, Inc.']
+  spec.email         = ['opensource@juul.com']
+
+  spec.summary       = "API client for We Ship Express V2."
+  spec.description   = spec.summary
+  spec.homepage      = 'https://github.com/JuulLabs-OSS/we_ship_client'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport'
+  spec.add_dependency 'dry-struct', '>= 0.6', '< 1.5'
+  spec.add_dependency 'dry-types'
+  spec.add_dependency 'loogi_http', '~> 1.0'
+
+  spec.add_development_dependency 'stub_env'
+  spec.add_development_dependency 'vcr'
+  spec.add_development_dependency 'webmock'
+end